How to generate and edit images with the GPT Image 2.5 API

To use GPT Image 2.5 through OpenAI’s Images API, choose gpt-image-2.5-flare or gpt-image-2.5-sunburst, then call client.images.generate() or client.images.edit(). The returned image data can be decoded from data[0].b64_json and saved locally.

The examples below follow OpenAI’s image generation guide, checked September 9, 2026. They have been checked against the documentation, not run through paid inference. They target OpenAI directly; a gateway needs its own verified model IDs, endpoint support, and pricing.

Choose the model before writing the request

These are starting choices, not guarantees about your images. See Flare vs Sunburst for selection criteria. The family name alone is not a substitute for an exact model ID.

Generate an image with Python

Install a current SDK and provide an OpenAI API key through OPENAI_API_KEY. Keep credentials outside source files.

python -m pip install --upgrade openai

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt=(
        "Create a clean product photograph of a ceramic tea cup on a "
        "warm gray background. Soft natural light, no text or watermark."
    ),
    size="1024x1024",
    quality="medium",
    output_format="png",
)

Path("tea-cup.png").write_bytes(
    base64.b64decode(result.data[0].b64_json)
)
print(result.usage)

This requests PNG output and saves those bytes as a PNG. Retain the response’s usage information when you evaluate costs; a successful image alone does not tell you how much the request consumed.

Edit a reference image

Use images.edit() with the input file. State what should change and what must remain intact. In this example, product.png is an existing local image.

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

with open("product.png", "rb") as reference:
    result = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=reference,
        prompt=(
            "Remove the background from this product photograph. "
            "Preserve the product shape, colors, and label text. "
            "Use a fully transparent background, with no checkerboard."
        ),
        size="1024x1024",
        quality="high",
        background="transparent",
        output_format="png",
    )

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

Inspect the output at full resolution. Check labels, geometry, and alpha transparency rather than assuming the preservation instruction was followed perfectly. A checkerboard painted into the image is not transparency. OpenAI’s prompting guide supplies further examples of localized edits and product preservation.

Set size and quality deliberately

Both models support auto, low, medium, high, xhigh, and max quality. Start with an explicit setting when comparing requests; auto makes controlled comparisons harder.

Recommended sizes include 1024x1024, 1536x1024, and 1024x1536. Custom dimensions must satisfy all of these rules:

• Width and height are multiples of 16.
• Neither edge exceeds 3,840 pixels.
• The aspect ratio is between 1:3 and 3:1.
• Total pixels are between 655,360 and 8,294,400.

OpenAI marks resolutions above 2560x1440 as experimental. “4K support” does not mean any arbitrary 4K dimensions will be accepted or equally reliable.

Use PNG or WebP for transparent output. output_compression applies to JPEG and WebP, not PNG. Higher quality settings deserve comparison on your inputs; they are not a promise that every image will improve.

Responses API: the image model belongs inside the tool

The Images API selects the image model directly. Responses separates the language model from the image-generation tool:

response = client.responses.create(
    model="gpt-6-astra",
    input="Generate a product photo of a ceramic tea cup on a gray background.",
    tools=[{
        "type": "image_generation",
        "model": "gpt-image-2.5-sunburst",
        "output_format": "png",
    }],
)

for index, item in enumerate(response.output):
    if item.type == "image_generation_call":
        Path(f"response-image-{index}.png").write_bytes(
            base64.b64decode(item.result)
        )

This continues from the Python imports and client above. OpenAI uses this outer-model/tool-model pattern in its documentation. Responses requests can also include the language model’s token charges; consult the pricing guide before comparing them with direct Images requests.

Before connecting a production workflow

Verify model access for the account and provider you will actually use. An SDK update cannot grant account access, and an OpenAI example does not demonstrate that another provider has deployed the same route.

Record the model, prompt, quality, dimensions, returned usage, latency, and output file. For edits, add checks for text accuracy and unintended changes. If replacing an existing GPT Image 2 workflow, follow the migration checklist before moving all traffic.