GPT Image 2.5 Node SDK 装不上？检查版本和类型报错

GPT Image 2.5 的 Node 项目还没发出请求就报错，先查实际加载的 openai 版本。 官方 v7.12.1 发布记录说明：7.12.0 没有发布到 npm，它包含的 Image 2.5 支持由 7.12.1 提供。安装失败、TypeScript 编译失败和服务端拒绝调用，要分别处理。

本文面向使用官方 OpenAI Node SDK 的开发者，核查日期为 2026 年 9 月 9 日。示例通过本地 TypeScript 编译；没有调用付费生图，因此不代表账户权限和生成效果已验证。Python 接入和改图见 Image 2.5 API 教程。

先看错误出在哪一步

保留第一个失败命令的输出。不要同时清缓存、换 Key、换端点，否则很难知道是哪一步起了作用。

查项目实际用的版本

在出错项目目录运行：

npm ls openai
npm config get registry
npm view openai@7.12.1 version

npm ls 看依赖树，npm view 查当前配置的 registry，两者回答的问题不同。多工作区项目要在实际应用所在工作区检查。使用 pnpm 或 Yarn 的项目沿用自己的包管理器，不要为了排错混用锁文件。

本次检查中，公共 registry 的 7.12.1可读取，7.12.0 返回 HTTP 404，与官方发布说明一致。私有镜像是否同步仍需单独检查。

npm 项目可以安装本次核验的版本：

npm install openai@7.12.1

检查 package.json 和锁文件的变化。安装成功后仍报同样错误，再查工作区解析的版本，并重启 TypeScript 进程。不要一上来删整个锁文件。

型号与画质参数要放在图片请求里

直连 OpenAI 时，使用 gpt-image-2.5-flare 或 gpt-image-2.5-sunburst。官方生成指南列出的画质值包括 low、medium、high、xhigh、max 和 auto。家族名 gpt-image-2.5 不能代替文档中的完整型号。

将下面代码保存为 generate.ts。它调用 Images API：

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

async function main() {
  const client = new OpenAI();
  const result = await client.images.generate({
    model: "gpt-image-2.5-flare",
    prompt: "A ceramic cup on a plain background, no text",
    size: "1024x1024",
    quality: "xhigh",
    output_format: "png",
  });
  const encoded = result.data?.[0]?.b64_json;
  if (!encoded) throw new Error("No image data in this response");
  await writeFile("cup.png", Buffer.from(encoded, "base64"));
  console.log(result.usage);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

项目没有 TypeScript 时，先安装开发依赖，再做不发请求的编译检查：

npm install --save-dev typescript @types/node
npx tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext generate.ts

要实际运行，去掉 --noEmit 编译，再执行 node generate.js。先通过环境变量或密钥管理器提供 OPENAI_API_KEY。执行生成脚本会产生付费请求，编译检查不会。

旧 SDK 可能允许任意型号字符串，你自己的封装也可能限制参数。先看诊断指出的类型来源，不要用 as any 掩盖尚未定位的错误，也不要断言所有旧版 SDK 都不能调用新模型。

如果是 API 返回错误

保存状态码、错误类型和 request ID，避免在日志中泄露 Key。核对服务地址与密钥是否属于同一平台；网关的带供应商前缀型号也不能直接照搬到 OpenAI 请求里。

模型找不到，按 模型 ID、端点和权限排查检查。尺寸被拒绝，看尺寸校验教程。成功请求的费用，看 Image 2.5 计费说明。依赖解析正确、编译通过、请求被接受、文件保存成功，是四项不同的验收。