GPT Image 2.5 API: Flare vs Sunburst, Python/cURL (+ GPT Image 2)

Updated in September 2026 for GPT Image 2.5. The code now targets gpt-image-2.5-flare, with notes for teams staying on gpt-image-2.

OpenAI released GPT Image 2.5 on September 8, 2026. In the API it is two models, gpt-image-2.5-flare and gpt-image-2.5-sunburst, and both use the same endpoints, base64 responses and most of the parameters that gpt-image-2 already had. An existing integration mostly needs a new model string, plus a decision about a few new options.

GPT Image 2.5 Flare vs Sunburst vs GPT Image 2: which API model to use

Start with Flare. Move a job to Sunburst when the same image goes through several rounds of edits and the details have to stay under control each time. For the two models on the same prompts, with timings, see Flare vs Sunburst: 6 same-prompt tests.

Compared with Images 2.0, OpenAI lists these changes in 2.5: more natural lighting and richer textures, better preservation of subjects from reference photos, more reliable edit following across multiple turns, and lower latency.

Prices are left out of the table on purpose. The API bills per token, and OpenAI's model pages say the 2.5 token rates match GPT Image 2. That doesn't make the cost per image equal, because a 2.5 image can use a different number of tokens at the same settings. Check the OpenAI API pricing page and measure your own requests before you budget.

To test prompts before you write any code, GPT Image 2.5 runs Flare and Sunburst in the browser. You don't need a ChatGPT account, and free starter credits cover the first tries.

Where to get an API key for GPT Image 2.5 and GPT Image 2

1. Create the key in the OpenAI dashboard. Sign in to the OpenAI API platform and open the API keys page. OpenAI's developer quickstart links straight to it.
2. Add credits. Image generation is paid. The rate-limit tables on the model pages list the free tier as not supported for all three models.
3. Check organization verification. OpenAI's image generation guide says you may need to complete API Organization Verification before GPT Image models work for your organization.
4. Put the key in an environment variable. Both official SDKs read OPENAI_API_KEY on their own, so it never has to appear in code.

# macOS / Linux
export OPENAI_API_KEY="sk-proj-your-key-here"

# Windows PowerShell
setx OPENAI_API_KEY "sk-proj-your-key-here"

Managed API key for production teams

If direct OpenAI access is unstable where your team works, or you want one relay that handles failover and billing aggregation, you can also get a managed GPT Image 2 API key by emailing support@gpt-image2.art. The relay keeps OpenAI's gpt-image-2 model name and parameters. Email us about GPT Image 2.5 Flare/Sunburst access.

GPT Image 2.5 API quick start: Python, Node.js and cURL

Install the SDK

# Python 3.10 or newer
pip install --upgrade openai

# Node.js 22 or newer
npm install openai@latest

Current releases of openai-python need Python 3.10+, and openai-node supports Node.js 22 and later. Upgrade even if the SDK is already installed: recent versions carry the 2.5 model IDs and quality values in their type definitions.

GPT Image 2.5 in Python

import base64
from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt=(
        "A white stainless steel water bottle on a beige linen tablecloth, "
        "soft morning window light, premium product photography"
    ),
    size="1024x1024",
    quality="medium",
)

with open("bottle.png", "wb") as f:
    f.write(base64.b64decode(result.data[0].b64_json))

GPT image models always return the image as base64 in b64_json, so the code decodes it and writes the file itself. Set n (1 to 10) for several images from one request.

GPT Image 2.5 in Node.js

// generate.mjs
import fs from 'node:fs';
import OpenAI from 'openai';

const client = new OpenAI(); // reads OPENAI_API_KEY

const result = await client.images.generate({
  model: 'gpt-image-2.5-flare',
  prompt:
    'A white stainless steel water bottle on a beige linen tablecloth, soft morning window light, premium product photography',
  size: '1024x1024',
  quality: 'medium',
});

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

The .mjs extension lets top-level await run as-is. If the key sits in a .env file, start it with node --env-file=.env generate.mjs.

GPT Image 2.5 with cURL

curl -s https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "A white stainless steel water bottle on a beige linen tablecloth, soft morning window light",
    "size": "1024x1024",
    "quality": "medium"
  }' \
  | jq -r '.data[0].b64_json' | base64 --decode > bottle.png

The JSON response carries the image in data[0].b64_json, so the command pipes it through jq and base64. If bottle.png is empty or won't open, run the request without the pipe and read the error body.

Staying on GPT Image 2? All three examples run unchanged with model set to gpt-image-2, or to the pinned gpt-image-2-2026-04-21.

GPT Image 2.5 API parameters and what changed from GPT Image 2

The original version of this guide also listed resolution, image_urls, callback_url and aspect-ratio values such as 16:9 for size. Those belong to some relay services, not to OpenAI's Image API. With OpenAI you set resolution through size and upload reference images as files.

GPT Image 2.5 API sizes and resolution

size accepts auto, the three standard sizes, or a custom WIDTHxHEIGHT string. The rules are the same for gpt-image-2, gpt-image-2.5-flare and gpt-image-2.5-sunburst:

• Width and height are both multiples of 16.
• The aspect ratio stays between 1:3 and 3:1.
• Neither side is longer than 3840 px.
• The total pixel count is between 655,360 and 8,294,400, which makes 3840x2160 the largest 16:9 frame.
• OpenAI marks resolutions above 2560x1440 as experimental.

A small pre-check catches the invalid ones before the request goes out:

def check_size(size: str) -> str:
    """Pre-check a size for gpt-image-2 and the GPT Image 2.5 models."""
    if size == "auto":
        return size
    width, height = (int(v) for v in size.lower().split("x"))
    problems = []
    if width % 16 or height % 16:
        problems.append("width and height must be multiples of 16")
    if max(width, height) > 3 * min(width, height):
        problems.append("aspect ratio must stay between 1:3 and 3:1")
    if max(width, height) > 3840:
        problems.append("no side may be longer than 3840 px")
    if not 655_360 <= width * height <= 8_294_400:
        problems.append("total pixels must be between 655,360 and 8,294,400")
    if problems:
        raise ValueError(f"{size}: " + "; ".join(problems))
    return size

OpenAI adds that a size also has to fit the model's current pixel and edge limits, so this is a pre-check, not a guarantee.

Quality levels and latency

OpenAI's guide suggests low for quick drafts and, for final assets, comparing the higher settings to balance detail, latency and cost. The same guide says complex prompts can take up to two minutes, and that jpeg output comes back faster than png.

GPT Image 2.5 image edits with cURL (up to 16 reference images)

The edits endpoint changes an existing image, builds a new image from reference images, or edits inside a masked area. One request takes up to 16 images, each a PNG, WebP or JPG under 50 MB.

curl -s https://api.openai.com/v1/images/edits \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "image[]=@bottle.png" \
  -F "image[]=@label-artwork.png" \
  -F "image[]=@marble-counter.jpg" \
  -F "image[]=@lemons.webp;type=image/webp" \
  -F "prompt=Put the bottle on the marble counter, wrap it in the paper label artwork and add two lemons beside it. Keep the shape and cap of the bottle unchanged." \
  -F "size=1536x1024" \
  -F "quality=high" \
  | jq -r '.data[0].b64_json' | base64 --decode > bottle-counter.png

Repeat -F "image[]=@file" once per reference image. Keep the brackets: image[] is the field name the official SDKs use when they send an array of images. curl sets image/png and image/jpeg from the file extension, but it may send .webp files as application/octet-stream, so the WebP line sets the type explicitly.

The same request in Python:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

MIME = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}
refs = ["bottle.png", "label-artwork.png", "marble-counter.jpg", "lemons.webp"]

def as_upload(path: str):
    p = Path(path)
    return (p.name, p.read_bytes(), MIME[p.suffix.lower()])

result = client.images.edit(
    model="gpt-image-2.5-flare",
    image=[as_upload(p) for p in refs],  # up to 16 files
    prompt=(
        "Put the bottle on the marble counter, wrap it in the paper label artwork "
        "and add two lemons beside it. Keep the shape and cap of the bottle unchanged."
    ),
    size="1536x1024",
    quality="high",
)

Path("bottle-counter.png").write_bytes(base64.b64decode(result.data[0].b64_json))

And in Node.js:

// edit.mjs
import fs from 'node:fs';
import path from 'node:path';
import OpenAI, { toFile } from 'openai';

const client = new OpenAI();

const MIME = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };
const refs = ['bottle.png', 'label-artwork.png', 'marble-counter.jpg', 'lemons.webp'];

const images = await Promise.all(
  refs.map((file) =>
    toFile(fs.createReadStream(file), path.basename(file), {
      type: MIME[path.extname(file).toLowerCase()],
    }),
  ),
);

const result = await client.images.edit({
  model: 'gpt-image-2.5-flare',
  image: images, // up to 16 files
  prompt:
    'Put the bottle on the marble counter, wrap it in the paper label artwork and add two lemons beside it. Keep the shape and cap of the bottle unchanged.',
  size: '1536x1024',
  quality: 'high',
});

fs.writeFileSync('bottle-counter.png', Buffer.from(result.data[0].b64_json, 'base64'));

Tips for edit requests:

• Name each reference by what it shows ("the paper label artwork") rather than by upload order, so the prompt still reads correctly if the file list changes.
• Say what must stay the same. A prompt that only lists changes leaves everything else open to reinterpretation.
• Use a mask to limit the area. Add -F "mask=@mask.png" in cURL or mask= in the SDKs. The mask is a PNG with an alpha channel, under 4 MB, in the same format and size as the image it edits; with several images, it applies to the first one. OpenAI describes GPT Image masking as prompt-based guidance, so the edit may not follow the mask edge exactly.

Migrating from gpt-image-2 to GPT Image 2.5

In most codebases the change is one line. The example also pins the dated snapshot:

 result = client.images.generate(
-    model="gpt-image-2",
+    model="gpt-image-2.5-flare-2026-09-08",
     prompt=prompt,
     size="1536x1024",
     quality="high",
 )

Before you move production traffic, go through this list:

1. Change the model string. gpt-image-2 becomes gpt-image-2.5-flare or gpt-image-2.5-sunburst. OpenAI doesn't list a plain gpt-image-2.5 ID.
2. Pin a dated snapshot. gpt-image-2.5-flare-2026-09-08 and gpt-image-2.5-sunburst-2026-09-08 lock the model version, as gpt-image-2-2026-04-21 does for GPT Image 2. Re-run your prompt tests before you move to a newer snapshot.
3. Guard the new quality levels. If one code path serves both models, make sure gpt-image-2 never receives xhigh or max.
4. Sizes carry over. Custom WIDTHxHEIGHT values follow the same rules on all three models: multiples of 16, an aspect ratio from 1:3 to 3:1, and at most 3840 px on the long side.
5. Transparent backgrounds work on both 2.5 models. On gpt-image-2 they are still a preview. Keep output_format at png or webp.
6. Check the Batch API. On September 15, 2026, OpenAI's model pages list Batch as supported for gpt-image-2 and not supported for either 2.5 model. Leave batch jobs where they are until that changes.
7. Compare token usage. Log usage for a sample of real requests on both models before you shift volume.
8. Review timeouts. Sunburst takes longer than Flare. The SDKs wait up to 10 minutes by default, but a proxy, serverless platform or job runner in front of them may give up much sooner.
9. Re-test edit prompts. OpenAI says 2.5 preserves subjects from reference photos better, so constraints you added to stop gpt-image-2 drifting from a reference may behave differently.

Everything else carries over: both endpoints, the SDK methods, base64 responses, reference images and masks, and the rest of the parameter table. OpenAI's guide now recommends the 2.5 models for new integrations, and gpt-image-2 remains available with its own snapshot.

Batch generation with the GPT Image 2.5 API

Image models have per-minute limits on tokens and on images (IPM) that grow with your usage tier. OpenAI lists them on each model's page, for example the GPT Image 2.5 Flare model page. Firing a hundred requests at once runs straight into them, so cap concurrency instead.

Python with asyncio:

import asyncio
import base64
from openai import AsyncOpenAI

client = AsyncOpenAI(max_retries=4)

async def generate_one(i: int, prompt: str, sem: asyncio.Semaphore) -> None:
    async with sem:
        result = await client.images.generate(
            model="gpt-image-2.5-flare",
            prompt=prompt,
            size="1024x1024",
            quality="low",
        )
    with open(f"draft-{i:03}.png", "wb") as f:
        f.write(base64.b64decode(result.data[0].b64_json))

async def main(prompts: list[str], concurrency: int = 4) -> None:
    sem = asyncio.Semaphore(concurrency)
    results = await asyncio.gather(
        *(generate_one(i, p, sem) for i, p in enumerate(prompts)),
        return_exceptions=True,
    )
    for i, r in enumerate(results):
        if isinstance(r, Exception):
            print(f"prompt {i} failed: {r!r}")

asyncio.run(main(["prompt one", "prompt two", "prompt three"]))

Node.js with p-limit (npm install p-limit):

// batch.mjs
import fs from 'node:fs';
import OpenAI from 'openai';
import pLimit from 'p-limit';

const client = new OpenAI({ maxRetries: 4 });
const limit = pLimit(4);
const prompts = ['prompt one', 'prompt two', 'prompt three'];

const results = await Promise.allSettled(
  prompts.map((prompt, i) =>
    limit(async () => {
      const result = await client.images.generate({
        model: 'gpt-image-2.5-flare',
        prompt,
        size: '1024x1024',
        quality: 'low',
      });
      fs.writeFileSync(`draft-${i}.png`, Buffer.from(result.data[0].b64_json, 'base64'));
    }),
  ),
);

results.forEach((r, i) => {
  if (r.status === 'rejected') console.error(`prompt ${i} failed:`, r.reason?.message);
});

Both SDKs already retry connection errors, 408, 409, 429 and 5xx responses twice, with a short exponential backoff. Raise max_retries (Python) or maxRetries (Node.js) when you want more attempts, rather than wrapping each call in a second retry loop.

Streaming partial images from GPT Image 2.5

With stream on, the API sends up to three partial images before the final one, enough for a progress preview in a UI. OpenAI's image generation guide shows this with the 2.5 models. You may get fewer partial images than you asked for if the final image finishes first, and each partial image adds 100 image output tokens.

import base64
from openai import OpenAI

client = OpenAI()

stream = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A white stainless steel water bottle on a beige linen tablecloth",
    size="1024x1024",
    stream=True,
    partial_images=2,
)

for event in stream:
    if event.type == "image_generation.partial_image":
        name = f"preview-{event.partial_image_index}.png"
    elif event.type == "image_generation.completed":
        name = "final.png"
    else:
        continue
    with open(name, "wb") as f:
        f.write(base64.b64decode(event.b64_json))

// stream.mjs
import fs from 'node:fs';
import OpenAI from 'openai';

const client = new OpenAI();

const stream = await client.images.generate({
  model: 'gpt-image-2.5-flare',
  prompt: 'A white stainless steel water bottle on a beige linen tablecloth',
  size: '1024x1024',
  stream: true,
  partial_images: 2,
});

for await (const event of stream) {
  if (event.type === 'image_generation.partial_image') {
    fs.writeFileSync(`preview-${event.partial_image_index}.png`, Buffer.from(event.b64_json, 'base64'));
  } else if (event.type === 'image_generation.completed') {
    fs.writeFileSync('final.png', Buffer.from(event.b64_json, 'base64'));
  }
}

The Python SDK doesn't retry a stream that fails while you are reading it, since replaying the request could duplicate output you already received. Handle a dropped stream in your own code.

GPT Image 2.5 API errors: codes, causes and fixes

In Node.js the error classes have matching names (OpenAI.BadRequestError, OpenAI.RateLimitError and so on, with APIConnectionTimeoutError for timeouts), and each error carries err.status, err.code and err.requestID. The Python version below sorts failures into outcomes a job queue can act on. It turns the SDK's own retries off, because the SDK retries every 429, billing errors included, and here the queue decides what to try again:

import base64
import openai
from openai import OpenAI

client = OpenAI(max_retries=0)  # the job queue decides what to retry

BILLING_CODES = {
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}

def generate(prompt: str) -> tuple[str, bytes | None]:
    try:
        result = client.images.generate(
            model="gpt-image-2.5-flare",
            prompt=prompt,
            size="1024x1024",
            quality="medium",
        )
        return "ok", base64.b64decode(result.data[0].b64_json)

    except openai.BadRequestError as e:
        if e.code == "moderation_blocked":
            body = e.body if isinstance(e.body, dict) else {}
            print("blocked:", body.get("moderation_details"), e.request_id)
            return "blocked", None  # show the user a generic message
        print("bad request:", e.message, e.request_id)
        return "fix_request", None  # the same payload fails again

    except openai.RateLimitError as e:
        if e.code in BILLING_CODES or e.type == "insufficient_quota":
            return "billing", None  # add credits or raise the limit
        return "retry_later", None  # requeue with a delay

    except (openai.AuthenticationError, openai.PermissionDeniedError) as e:
        print("account problem:", e.status_code, e.request_id)
        return "check_account", None  # fix the key, project or region

    except (openai.APIConnectionError, openai.InternalServerError):
        return "retry_later", None

OpenAI suggests keeping the message to end users generic and saving moderation_details for your logs and support tools.

Common integration mistakes

Production checklist for a GPT Image 2.5 integration

• API key in an environment variable or secret manager, never in code or logs
• Model pinned to a dated snapshot
• size validated before the request goes out
• low quality for drafts; high, xhigh or max only where you compared the results
• Concurrency capped below your tier's images-per-minute limit
• No automatic retries for moderation blocks, bad requests or billing errors
• Request IDs logged for every failed call
• usage logged per model and quality, and a spend limit set on the OpenAI project
• User prompts screened on your side, with a generic message when a request is blocked
• Repeated requests served from a cache keyed on prompt, model, size and quality
• Decoded images written to your own storage
• Proxy and serverless timeouts long enough for Sunburst

GPT Image 2.5 API FAQ

What is the GPT Image 2.5 API model name? gpt-image-2.5-flare or gpt-image-2.5-sunburst. The dated snapshots are gpt-image-2.5-flare-2026-09-08 and gpt-image-2.5-sunburst-2026-09-08.

Should I use Flare or Sunburst? Flare by default. Test Sunburst for edit-heavy work that needs tighter control across rounds, and allow for its longer generation times.

Is the GPT Image 2.5 API free? No. It is billed per token, and OpenAI's rate-limit tables don't offer a free tier for it. For prompt testing without an API key, the browser generator mentioned near the top of this guide comes with free starter credits.

How much does GPT Image 2.5 cost per image? It depends on size, quality and how many tokens each image uses. OpenAI publishes per-token rates on its pricing page, and the usage field in your own responses gives you the token counts to multiply.

What resolutions does the GPT Image 2.5 API support? The three standard sizes, plus custom WIDTHxHEIGHT values with both sides divisible by 16, an aspect ratio between 1:3 and 3:1, at most 3840 px on the long side, and 655,360 to 8,294,400 pixels in total. That allows both 3840x2160 and 2160x3840, though OpenAI marks sizes above 2560x1440 as experimental.

Can the GPT Image 2.5 API do image-to-image? Yes. Use the edits endpoint, /v1/images/edits (images.edit in the SDKs), to change an existing image or build a new one from reference images. The editing section above has the code.

How do I generate a transparent PNG? Set background to transparent and output_format to png or webp. Both 2.5 models support it.

What is the maximum prompt length? 32,000 characters for GPT image models.

What are the GPT Image 2.5 rate limits? They depend on your usage tier. Each model page in OpenAI's docs lists tokens per minute and images per minute by tier.

Does the GPT Image 2.5 API support streaming? Yes. Set stream to true and partial_images to a value from 0 to 3.

Can I keep using gpt-image-2? Yes. It is still listed with its own snapshot. The endpoints are the same and most parameters match (the parameter table shows the differences), so you can move traffic one job type at a time.

Need a managed GPT Image 2 API key?

If you'd rather skip account setup, billing, region issues and rate-limit tuning, you can buy a managed GPT Image 2 API key by emailing support@gpt-image2.art. We provide:

• One stable API endpoint with built-in failover
• Aggregated billing in your local currency, with no USD wire transfer
• Async task mode with callback support
• Volume pricing for teams generating more than 10K images a month
• The same gpt-image-2 model name and parameter spec as the official API

Email us about GPT Image 2.5 Flare/Sunburst access.

Further reading

• GPT Image 2.5 Flare vs Sunburst: 6 Same-Prompt Tests
• GPT Image 2 examples and prompts: finished images with the prompts that made them
• GPT Image 2 Prompt Writing Guide: 7 Rules for 90% Hit Rate
• GPT Image 2 Style Library: 12 Copy-Paste Art Style Prompts
• What is GPT Image 2? A Complete Introduction

gpt-image2.art is an independent site and is not affiliated with OpenAI.