GPT Image 2.5 Node SDK: fix install and type errors

If your GPT Image 2.5 Node project fails before sending a request, check the installed openai package first. OpenAI’s v7.12.1 release includes Image 2.5 support from v7.12.0, which was not published to npm. A missing package version, a TypeScript error and an API access error require different fixes.

This guide is for developers using the official OpenAI Node SDK. The package metadata was checked on September 9, 2026. The example passed local TypeScript compilation with openai 7.12.1 and TypeScript 5.9.3; no paid generation was run. Compilation does not verify account access or image quality. For Python and editing, start with the GPT Image 2.5 API guide.

Find the stage that failed

Keep the first failing command and its output. Do not clear caches, change keys and change endpoints together: that makes it harder to identify the cause.

Check the package your application actually resolves

Run these commands in the project that contains the failing code:

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

npm ls inspects the dependency tree. npm view asks the configured registry about a package; it does not tell you what your application imports. In a monorepo, inspect the relevant workspace as well as the root. If you use pnpm or Yarn, use that project’s dependency manager and preserve its lockfile workflow.

The public registry record for 7.12.1 was available during our check. The corresponding 7.12.0 request returned HTTP 404. This agrees with the release notes; it is not evidence that a private registry mirror has already synchronized.

For an npm project, a version pinned to the release checked here is:

npm install openai@7.12.1

Review the package and lockfile diff. If installation succeeds but the same error remains, rerun npm ls openai in the application workspace and restart its TypeScript process. Avoid deleting the entire lockfile as a first repair.

Put model and quality on the image request

The two documented OpenAI model IDs are gpt-image-2.5-flare and gpt-image-2.5-sunburst. The family name gpt-image-2.5 is not a substitute for either documented ID. The image generation guide documents xhigh and max in addition to low, medium, high and auto.

Save the following as generate.ts. It uses the Images API, not Chat Completions:

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;
});

If TypeScript is not installed in this project, add it and the Node types as development dependencies. Compile without calling the API:

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

To run the example, compile it with the same options but without --noEmit, then execute node generate.js. Supply OPENAI_API_KEY through your environment or secret manager first. Running the script sends a billable generation request; the compilation command does not.

An older SDK may still accept arbitrary model strings. Conversely, your own wrapper can reject a new value even after the SDK has been updated. Inspect the type named in the compiler diagnostic; do not use as any to hide an error you have not identified.

If the error comes from the API

Record the response status, error type and request ID without publishing the key. Check the base URL and credential together. A key for one service is not interchangeable with another service’s key, and a provider-qualified gateway model ID should not be copied blindly into a direct OpenAI request.

For a model-not-found response, use the ID, endpoint and permission checks. For rejected dimensions, use the size guide. For the cost of a successful request, use Image 2.5 pricing.

The repair is complete when the correct package resolves, the image request compiles, the account accepts the request and the returned bytes are saved successfully. Those are separate checks; passing one should not be reported as passing all four.