Node.js 图片 API SDK 教程：multipart 编辑与 Base64 保存

固定 Node 与 SDK 版本，先做本地输入检查

2026-10-07 核对的官方 Node SDK 版本为 7.30.0，支持 Node 22 和 24 LTS。这个 .mjs 脚本使用 Node 原生模块，默认 dry-run 不请求 API，也不导入 SDK；主动执行时才读取自己的 Key 并调用模型。

下载脚本经过本地输入与语法检查，没有用它发起 apizt 付费调用。各渠道是否接受示例字段，要以当前模型广场和接入文档为准。

node --version
npm init -y
npm install --save-exact [email protected]
npm list openai
node image-task.mjs --prompt-file prompt.txt

Key 留在服务端，SDK 根地址只填一次

将自己的 Key 放进 tokenba_API_KEY 环境变量，服务端实例读取它。不要写入前端组件、公开仓库或 NEXT_PUBLIC_ 变量；本例也不设置 dangerouslyAllowBrowser。

baseURL 以 /v1 结束，SDK 自动追加 images endpoint。生成请求设 maxRetries:0，并明确 timeout:180000，避免单个图片任务在断线时被自动重复尝试。

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.tokenba_API_KEY,
  baseURL: "https://api.apizt.com/v1",
  maxRetries: 0,
  timeout: 180000,
});

const result = await client.images.generate({
  model: "gpt-image-2",
  prompt: "奶油白马克杯的虚构商品概念图，不添加文字和品牌",
  size: "1024x1024",
  output_format: "png",
  n: 1,
});

• 核对 API 根地址与 endpoint

用 toFile 上传原图，交给 SDK 生成 multipart

下载脚本先限制原图在 20 MB 内，再读取文件并用 toFile 包装。它是本教程的本地限制，不代表任意渠道都接受 20 MB；实际允许格式和大小需要按所选接口核对。

SDK 会生成 multipart 内容与 boundary，不要把 Content-Type 强制写成 application/json。编辑提示词要明确改动区域、保留区域和原图中的标签；只给文件路径或只写提示词都不是完整的图生图请求。

import fs from "node:fs/promises";
import { toFile } from "openai";

const bytes = await fs.readFile("original.png");
const image = await toFile(bytes, "original.png");
const result = await client.images.edit({
  model: "gpt-image-2",
  image,
  prompt: "只替换背景为浅米色，保留主体的轮廓、颜色、标签和数量",
  size: "1024x1024",
  output_format: "png",
  n: 1,
});

• 检查 GPT Image 2 编辑与返回协议

保存 Base64；URL 返回先停下来核对

完整脚本验证 Base64、解码大小和 PNG 签名，保存新文件而不覆盖旧结果，并读取文件内实际宽高。元数据包含 request ID、usage 和文件 hash，费用字段保持 unverified。

若 data 为空或只有 URL，脚本不会自动再次生成，也不会把 Authorization 发往下载地址。先检查当前渠道返回协议；URL 可能有有效期，应核对地址后手工保存或单独实现受限制的下载逻辑。

.withResponse() 可同时拿到 SDK 数据和原始响应头；x-request-id 是否提供取决于渠道。没有请求 ID 时保留实际时间、型号与任务 ID，不能自行构造一个当作服务端凭证。

const { data, response } = await client.images.generate({
  model: "gpt-image-2", prompt: "虚构马克杯概念图", n: 1,
  size: "1024x1024", output_format: "png",
}).withResponse();

const encoded = data.data?.[0]?.b64_json;
if (!encoded) throw new Error("未返回 Base64，先核对渠道协议");
await fs.writeFile("new-result.png", Buffer.from(encoded, "base64"), { flag: "wx" });
console.log({ requestId: response.headers.get("x-request-id") });

显式提交一次，出现超时先追踪原请求

把 .mjs 脚本和 prompt.txt 放入同一目录，先完成 dry-run。确认价格和参数后加 --run；每条带 --run 的命令都是一次独立调用。不要为了测试安装而重复运行付费命令。

编辑时使用自己的 original.png 和 edit-prompt.txt。如果出现连接中断、超时或结果保存错误，先核对原请求日志与账单。脚本禁用 SDK 自动重试，不承诺请求失败就不会扣费。

node image-task.mjs --prompt-file prompt.txt --run

node image-task.mjs --mode edit --image original.png --prompt-file edit-prompt.txt --output edited.png
node image-task.mjs --mode edit --image original.png --prompt-file edit-prompt.txt --output edited.png --run

放进 Web 应用时，给长任务留出查询路径

先运行这个本地服务端脚本，再选择自己的后端运行方式。图片生成可能等待较长时间；Web 平台的函数超时、上传大小和持久文件系统限制，需要在部署环境另行核对，不能直接假定一个 Next.js 路由能等满 180 秒。

生产流程可以由受控后端接收任务，保存输入版本、请求状态和结果位置，再提供任务查询。鉴权、访问权限、取消与重复提交控制需要应用实现；本示例没有托管任务队列或自动计费归因。

怎样确认已经完成

• 把模型广场中自己令牌实际可用的模型 ID、Images 协议、价格和尺寸保存到任务记录。
• dry-run 只核对本地输入；只有主动添加 --run 才发送一次请求。
• 收到 HTTP 成功后仍检查 data、b64_json、实际图片宽高与内容；不能只检查请求状态。
• 记录请求 ID 和 usage；实际扣费去控制台请求日志核对，不把 usage 直接称为账单。
• 连接中断或超时后先查日志；本地没收到图片也可能已完成生成，不能直接重复发送。

常见问题

资料来源

• OpenAI 官方 SDK 安装说明
• OpenAI Images：生成、编辑与 Base64 保存
• apizt 既有编辑记录：尺寸和费用边界
• 官方 Node SDK：toFile、原始响应、重试与运行环境
• 本页核对的 Node SDK 7.30.0 发布记录