Node.js / TypeScript

Node.js / TypeScript 适合 Web 后端、Server Actions、队列任务和自动化工具。不要在浏览器端直接暴露 Tapapi API Key。

以下示例默认运行在服务端、脚本、队列 worker、Next.js Route Handler 或 Server Action 中。不要把 Tapapi API Key 放进浏览器前端、移动端包、公开仓库或客户端配置。

安装

npm install openai

环境变量

TAPAPI_API_KEY=sk-xxx
TAPAPI_BASE_URL=https://tapapi.ai/v1

初始化客户端

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TAPAPI_API_KEY,
  baseURL: process.env.TAPAPI_BASE_URL || "https://tapapi.ai/v1",
  timeout: 120_000,
});

OpenAI Node SDK 的 timeout 单位是毫秒。SDK 默认会对部分网络错误、429 和 5xx 做有限重试；生产系统仍然需要自己的业务 task_id、幂等记录和并发控制。

文本请求

const resp = await client.chat.completions.create({
  model: "gpt-5.4",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "用一句话解释 Tapapi 是什么" },
  ],
});

console.log(resp.choices[0]?.message?.content);

流式输出

const stream = await client.chat.completions.create({
  model: "gpt-5.4",
  stream: true,
  stream_options: { include_usage: true },
  messages: [{ role: "user", content: "写一段 100 字的产品介绍" }],
});

for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
}

流式响应通常读取 choices[0].delta.content。生产解析时要跳过空内容、保活事件和没有普通文本 delta 的 chunk；最终 usage 可能受上游或网络影响缺失，计费以控制台账单记录为准。

Responses 请求

/v1/chat/completions 是 Node.js 接入的默认主线。需要 Responses API 时，先确认你的 openai SDK 版本、模型详情和返回字段：

const resp = await client.responses.create({
  model: "gpt-5.4",
  input: "用一句话解释 Tapapi 是什么",
});

console.log(resp.output_text);

Responses 的返回结构和 Chat Completions 不完全一样，不要共用同一套解析代码。

图片生成

const image = await client.images.generate({
  model: "nano-banana-pro",
  prompt: "a clean product photo of a white ceramic mug",
  n: 1,
  size: "1024x1024",
  response_format: "url",
});

if (!image.data?.length) {
  throw new Error("Tapapi returned empty image data");
}

const item = image.data[0];
const output = item.url || item.b64_json;

if (!output) {
  throw new Error("Tapapi returned image data without url or b64_json");
}

console.log(output);

图片返回可能是 url 或 b64_json。生产环境建议把图片转存到自己的对象存储，不要长期依赖临时 URL。批量生成时还要记录请求 n、实际返回数量和成功转存数量；如果响应包含 metadata.tapapi_partial，按实际返回张数处理。

保存图片结果

import { writeFile } from "node:fs/promises";

async function saveImageItem(
  item: { url?: string | null; b64_json?: string | null },
  path: string
) {
  if (item.url) {
    const response = await fetch(item.url);

    if (!response.ok) {
      throw new Error(`Image download failed: ${response.status}`);
    }

    const bytes = Buffer.from(await response.arrayBuffer());
    await writeFile(path, bytes);
    return;
  }

  if (item.b64_json) {
    await writeFile(path, Buffer.from(item.b64_json, "base64"));
    return;
  }

  throw new Error("image item has no url or b64_json");
}

await saveImageItem(item, "output.png");

如果 URL 下载失败，优先重试下载和转存，不要立刻重新生成图片。

原生 fetch

async function safeJson(response: Response) {
  try {
    return await response.json();
  } catch {
    return {};
  }
}

function parseTapapiError(response: Response, payload: any) {
  const error = payload?.error || {};

  return {
    status: response.status,
    request_id: response.headers.get("X-Oneapi-Request-Id"),
    type: error.type,
    code: error.code || payload?.code,
    message: error.message || payload?.message || response.statusText,
  };
}

const response = await fetch("https://tapapi.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TAPAPI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-5.4",
    messages: [{ role: "user", content: "Hello" }],
  }),
});

const data = await safeJson(response);

if (!response.ok) {
  throw new Error(JSON.stringify(parseTapapiError(response, data)));
}

console.log(data.choices[0].message.content);

SDK 错误处理

try {
  const resp = await client.chat.completions.create({
    model: "gpt-5.4",
    messages: [{ role: "user", content: "Hello" }],
  });

  console.log(resp.choices[0]?.message?.content);
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    console.error({
      status: err.status,
      request_id: err.request_id,
      code: err.code,
      message: err.message,
    });
  }

  throw err;
}

OpenAI SDK 的 request_id 通常来自上游标准 x-request-id。Tapapi 排障时还要优先保存响应头里的 X-Oneapi-Request-Id；如果你需要完整请求标识，建议在关键路径使用原生 fetch 或 SDK 的 raw response 能力读取 headers。

超时控制

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 120_000);

try {
  const response = await fetch("https://tapapi.ai/v1/images/generations", {
    method: "POST",
    signal: controller.signal,
    headers: {
      Authorization: `Bearer ${process.env.TAPAPI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "nano-banana-pro",
      prompt: "a product photo of a white mug",
      size: "1024x1024",
    }),
  });

  const data = await safeJson(response);

  if (!response.ok) {
    throw new Error(JSON.stringify(parseTapapiError(response, data)));
  }

  if (!data.data?.length) {
    throw new Error("Tapapi returned empty image data");
  }

  const item = data.data[0];
  console.log(item.url || item.b64_json);
} finally {
  clearTimeout(timer);
}

客户端超时只代表你的进程不再等待响应，不一定代表上游任务没有执行。遇到 AbortError、504 或 524 时，先查自己的业务任务状态、Tapapi 账单和日志，再决定是否补跑。

生产建议

场景	建议
Next.js	用 Route Handler 或 Server Action 做服务端代理，不要在 Client Component 里调用 Tapapi
API Key	只放服务端环境变量，不放 URL query、前端代码或公开配置
批量任务	加队列和并发限制，不要一次性并发打满
重试	只对 429、临时 5xx、网络中断做有限重试，并加随机抖动
幂等	每个业务任务保存自己的 `task_id`，避免重复点击或 worker 重启重复请求
日志	保存接口、模型、HTTP 状态码、`request_id`、错误字段和最终用量
图片保存	同时兼容 `url` 和 `b64_json`，成功后尽快转存
视频 API	受控开放，先看视频 API，不要默认写进批量任务

下一步

场景	文档
OpenAI SDK 迁移总览	OpenAI SDK 迁移
不使用 SDK	HTTP REST
Python 完整示例	Python
PHP / Laravel	PHP / Laravel
Next.js 代理	Next.js 代理接入
生产上线检查	上线 Checklist

SDK 与语言

常用工具

安装

环境变量

初始化客户端

文本请求

流式输出

Responses 请求

图片生成

保存图片结果

原生 fetch

SDK 错误处理

超时控制

生产建议

下一步

​安装

​环境变量

​初始化客户端

​文本请求

​流式输出

​Responses 请求

​图片生成

​保存图片结果

​原生 fetch

​SDK 错误处理

​超时控制

​生产建议

​下一步

安装

环境变量

初始化客户端

文本请求

流式输出

Responses 请求

图片生成

保存图片结果

原生 fetch

SDK 错误处理

超时控制

生产建议

下一步