GPT Image 2.5 API Guide: Generate and Edit Images with Sunburst and Flare

Use the Image API for direct single-step generations and edits. Use the Responses API when image creation belongs inside a conversational or multi-step flow. In the Image API, select gpt-image-2.5-sunburst or gpt-image-2.5-flare directly.

Choose the Interface First

The Image API exposes generation and edit endpoints. The Responses API supports iterative image generation as a tool and can keep image inputs and outputs in context. This architecture decision matters more than SDK syntax.

Minimal Generation Pattern

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();
const result = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "A clean editorial illustration of a solar-powered library, no text",
  size: "1536x1024",
  quality: "medium",
  output_format: "png"
});

fs.writeFileSync("library.png", Buffer.from(result.data[0].b64_json, "base64"));

Keep API keys server-side and outside source control.

Output Controls

Both models support auto through max quality, custom dimensions within official limits, PNG/JPEG/WebP, compression for JPEG/WebP, and transparent or opaque backgrounds. Use PNG or WebP for alpha.

Editing Pattern

Call the edit endpoint with one or more images and a prompt that separates change from preserved details. Validate input types and size before sending. Give each reference a role.

Production Validation

Store request ID, model or snapshot, prompt version, size, quality, output format, references, latency and acceptance result. Retry only transient failures; do not automatically retry a semantically wrong output without changing the request.

Model Routing

Route validated everyday jobs to Flare and demanding precision jobs to Sunburst. Use a fixed benchmark and avoid assuming the faster model is cheaper, because current token rates match.

Error Handling

Handle authentication, organization verification, rate limits, invalid dimensions, moderation and empty output. Use exponential backoff with jitter for eligible transient errors and cap attempts. Never log private image data unnecessarily.

Downstream Animation

After decoding and approving an image, store provenance and pass the asset to a downstream workflow. Elser AI is relevant when the still must become a character-led storyboard, video or edited animation. Verify supported upload and model options in the live product.

Generation vs Editing Endpoints

Use generations for a new image from text. Use edits when one or more existing images define the subject or starting state. For multi-reference edits, send inputs in a stable order and identify that order in the prompt. Validate file type and dimensions before the request so bad inputs fail locally.

Responses API for Iterative Work

The Responses API is useful when a user creates an image, evaluates it conversationally and requests a follow-up change. The image-generation tool can participate in a larger response flow, and image file IDs can remain in context. This reduces application-side stitching, but the product still needs explicit state and version control. “Same as before” is not enough for a critical constraint; restate it.

A Safer Application Architecture

Keep client, job queue, asset store and metadata store separate. The client submits a brief. The server validates it and creates a job. A worker calls OpenAI, decodes the result and stores it under a generated asset ID. Metadata records the model snapshot, prompt, settings, references and moderation outcome. The client receives a short-lived asset URL rather than raw credentials.

Long-running calls should not tie up a fragile browser request. Complex prompts may take significant time, so expose pending, complete and failed states. Make job submission idempotent to avoid duplicate charges when a client retries.

Validation Rules

Check custom dimensions against the documented multiple-of-16, edge, ratio and total-pixel constraints. Require PNG or WebP when background is transparent. Clamp compression to the supported range. Allow only known quality and model values. Reject a missing prompt before the API call.

Reliability and Observability

Record request ID, HTTP status, error class, attempts and latency without logging private images or secrets. Retry rate limits and eligible server errors using exponential backoff with jitter. Do not retry authentication, invalid parameter or policy errors unchanged. Put a cap on attempts and return a useful product message.

Monitor:

• Success and accepted-image rates.
• p50 and p95 latency by model and quality.
• Input and output tokens.
• Retries and duplicated jobs.
• Moderation outcomes.
• Storage and delivery failures.

Security and Rights

Store the API key in a server-side secret manager. Apply access control to source and generated images. Set retention rules, remove metadata that should not be exposed, and document user rights to uploaded material. OpenAI notes that organization verification may be required for GPT Image model access; handle that as an onboarding prerequisite, not a runtime surprise.

Snapshot Strategy

Use the undated ID when you want ongoing model updates. Pin a dated snapshot when reproducibility is more important. Evaluate a new snapshot with the same benchmark before changing production traffic. Store the actual model identifier returned or configured with each asset.

If a launch article includes code, display the dated verification date beside it. Readers should understand that model availability, SDK syntax, rate limits and organization requirements can change independently of the article's conceptual architecture.

A Typed Request Contract

Define an internal schema even though the image model itself does not provide Structured Outputs. A job might contain prompt, workflow, model, quality, width, height, format, background, compression, reference asset IDs and an idempotency key. Validate it before translating to an SDK call.

Do not expose arbitrary model names or file paths from a browser. Map a small client-facing option set to server-approved values. Resolve references from access-controlled asset IDs and verify that the current user can read them.

Editing Request Sketch

import OpenAI from "openai";
import fs from "fs";

const client = new OpenAI();

const result = await client.images.edit({
  model: "gpt-image-2.5-sunburst",
  image: [fs.createReadStream("approved-character.png")],
  prompt: `Change only the coat to dark green wool.
Preserve face, hair, eye colors, pose, hands, framing and background.
Add no text, jewelry or other people.`,
  size: "1024x1536",
  quality: "high",
  output_format: "png"
});

const bytes = Buffer.from(result.data[0].b64_json, "base64");
fs.writeFileSync("character-green-coat.png", bytes);

The exact SDK surface can evolve, so validate examples against the current official guide before deployment. Production code should stream or buffer responsibly, validate response presence and store atomically rather than assuming every call returns usable data.

Idempotency and Duplicate Cost

A user double-click or network retry can submit the same expensive generation twice. Assign an idempotency key at job creation, persist the job before dispatch and return the existing job when the same key reappears. The worker should acquire the job once and record terminal state.

If you intentionally generate multiple variants, represent that as one explicit product action rather than accidental retries. The Image API supports n for multiple images where documented, but your cost and review model should count every output.

Moderation and Failure UX

All prompts and images are subject to safety filtering. Avoid revealing sensitive internal moderation detail, but give users enough guidance to revise a legitimate request. Separate policy rejection from invalid settings, authorization, rate limiting and transient service failure.

Never silently substitute a different model when Sunburst is unavailable; that can violate a quality or contractual expectation. Return a clear status or use a fallback only when the product has disclosed and logged that behavior.

Asset Storage and Delivery

Decode base64 in memory with a size limit, verify the claimed format, generate a checksum and store the immutable original. Derive thumbnails separately. Serve through short-lived signed URLs and appropriate content types. Preserve alpha for transparent PNG/WebP and avoid a lossy conversion that destroys the deliverable.

Store prompts and references with access controls appropriate to their sensitivity. Define retention and deletion behavior. A generated file without provenance is difficult to audit, reproduce or safely hand to an Elser animation project.

Pre-Launch Checklist

• Account and organization access are confirmed.
• API key is server-side and rotatable.
• Model IDs and dimension rules are allowlisted.
• Job submission is idempotent.
• Retries are bounded and classified.
• Usage, latency and acceptance are monitored.
• Images and metadata have retention rules.
• Human review exists for identity, brand and text-sensitive outputs.
• A dated snapshot strategy and rollback path are documented.

FAQ

Which API should I choose?

Image API for direct generation/editing; Responses API for conversational or multi-step image experiences.

Can I request multiple images?

The Image API supports an n parameter for multiple outputs where documented.

Does the API return a URL?

The current guide shows base64-encoded image data for the Image API; decode and store it securely.

Conclusion

A reliable integration couples clear model routing with strict validation, observability and asset review. Build the smallest direct request first, then add conversational state or downstream animation only when the core image path is dependable.