How to Generate and Edit Images with GPT-Image-2.5

OpenAI's GPT-Image-2.5 models are now available through the Images API, giving developers two new options for image-generation workflows: GPT-Image-2.5 Flare for faster everyday generation and GPT-Image-2.5 Sunburst for workflows where editing precision matters more. Both models accept text and image inputs and return generated images. OpenAI also supports quality levels up to max, transparent backgrounds, flexible image sizes, and image editing through the API.

This tutorial shows how to generate an image with GPT-Image-2.5, save the returned image locally, edit an existing image, and choose between the two models. The examples use Python and the official OpenAI SDK, but the same API can also be accessed through the image-generation endpoint directly.

What GPT-Image-2.5 Adds to an AI Image App

GPT-Image-2.5 is split into two API models with different intended uses. Flare is the faster option for everyday image generation, while Sunburst is designed for more demanding generation and editing workflows where preserving details during changes matters more. Both models support text and image input, and both can produce image output.

The API also supports quality settings including low, medium, high, xhigh, max, and auto for these models. That gives an application more control over the trade-off between generation quality and processing cost.

Prepare the Python Environment

Install the current OpenAI Python package and configure an API key as an environment variable. Keeping the key outside the source code prevents it from being accidentally committed to a repository or exposed in a browser application.

pip install -U openai

Then configure the key in your operating system:

export OPENAI_API_KEY="your-api-key"

On Windows, you can create the same environment variable through PowerShell or the Windows environment-variable settings. The OpenAI SDK automatically reads OPENAI_API_KEY when you create the client without explicitly passing a key.

Generate Your First Image

The simplest request uses the Images API's generation method. Choose a model, describe the image in the prompt, and specify the desired size and quality.

from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt=(
        "A modern desktop workspace with a laptop displaying "
        "a clean AI development dashboard, realistic lighting, "
        "professional technology photography"
    ),
    size="1536x1024",
    quality="medium",
)

print(result.data[0].b64_json)

GPT image models return image data as Base64 rather than a temporary image URL. Base64 is an encoding that represents binary image data as text, allowing the application to decode and save the generated image itself. The current API reference states that the URL-style response format is not supported for GPT image models.

Save the Generated Image

For an actual application, decode the returned Base64 data and write it to a file. The following example saves the result as a PNG image:

import base64
from openai import OpenAI

client = OpenAI()

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A futuristic AI workstation in a dark modern studio",
    size="1536x1024",
    quality="medium",
    output_format="png",
)

image_bytes = base64.b64decode(result.data[0].b64_json)

with open("ai-workstation.png", "wb") as file:
    file.write(image_bytes)

print("Image saved as ai-workstation.png")

The output format can be PNG, JPEG, or WebP for GPT image models. PNG is useful when you need lossless output, while JPEG and WebP can reduce file size for websites and applications.

Choose the Right Model

For a typical image-generation feature, start with gpt-image-2.5-flare. OpenAI describes Flare as the faster model for high-quality everyday image generation, making it suitable for product images, social content, visual prototypes, and high-volume generation.

Use gpt-image-2.5-sunburst when the workflow depends more heavily on precise editing or maintaining visual details across changes. OpenAI describes Sunburst as its more capable image-generation and editing model and specifically positions it for workflows where editing precision matters most.

The choice does not have to be permanent. An application can use Flare for ordinary requests and route selected editing or high-precision jobs to Sunburst.

Control the Image Dimensions

The newer GPT image models support arbitrary image resolutions within the API's current constraints. Width and height must be divisible by 16, the aspect ratio must remain between 1:3 and 3:1, and the documented maximum supported resolution is 3840 by 2160.

That makes the API useful for website-specific formats instead of forcing every generated image into a fixed square. For example, a 16:9 article thumbnail can use a resolution such as 1536x864:

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A cinematic technology newsroom with futuristic AI displays",
    size="1536x864",
    quality="high",
)

Using the target dimensions directly can reduce the amount of resizing your application has to perform after generation. For production systems, still validate the requested dimensions before sending them to the API so invalid user input does not become a failed request.

Generate an Image with a Transparent Background

Transparent output is useful for product cards, logos, application assets, and other designs where the generated subject needs to sit on a background supplied by your own interface. GPT-Image-2.5 Flare and Sunburst support transparent and opaque background settings. When transparency is requested, the output format should be PNG or WebP.

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A polished 3D icon of a small futuristic robot",
    size="1024x1024",
    quality="high",
    background="transparent",
    output_format="png",
)

This approach is particularly useful when your application needs to place the generated object over different backgrounds. Instead of generating a complete scene every time, you can generate an isolated visual element and compose it elsewhere.

Edit an Existing Image

Image editing becomes more useful when the application already has a source image. For example, an online store could allow a seller to upload a product photograph and request a different background while keeping the product itself recognizable. OpenAI positions Sunburst specifically for workflows that require more precise image editing.

A basic editing workflow sends the original image together with instructions describing the change. The exact input-file handling depends on the SDK version you are using, so keep the OpenAI package current and follow the current image-edit method exposed by your installed SDK.

from openai import OpenAI

client = OpenAI()

with open("product.png", "rb") as image_file:
    result = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=image_file,
        prompt=(
            "Keep the product unchanged. Replace the background "
            "with a clean modern studio background and preserve "
            "the original product proportions and details."
        ),
    )

print(result.data[0].b64_json)

The important part of the prompt is the distinction between what should change and what should remain unchanged. A request such as “change the background” provides a narrower editing instruction than asking the model to recreate the entire product scene.

Write Better Image Prompts

Image prompts work better when they describe the actual visual requirements rather than relying on a collection of style keywords. Start with the subject, then describe its position, environment, lighting, composition, and any details that must remain consistent. OpenAI says GPT-Image-2.5 improves instruction following for focused edits and is better at preserving subjects and surrounding details during image changes.

For example, instead of writing a vague prompt such as AI laptop, specify the intended composition:

prompt = """
Create a realistic 16:9 technology editorial image.
Place a premium laptop slightly right of center on a clean desk.
Show an AI development interface on the display.
Use soft studio lighting and a dark blue-gray environment.
Leave clean negative space on the left side for an article title.
Do not add logos, watermarks, or unrelated text.
"""

Negative requirements can be useful when an application needs a controlled composition. However, do not overload the prompt with dozens of unrelated constraints. Give the model the information that affects the actual visual result.

Use Quality Levels Deliberately

Quality is an API parameter rather than something that needs to be encoded into every prompt. GPT-Image-2.5 supports low, medium, high, xhigh, max, and auto.

A practical application can start previews at a lower quality and request a higher quality version only after the user approves the concept. This prevents every exploratory prompt from automatically becoming a maximum-quality generation. For an automated publishing pipeline, the right quality setting depends on how much visual refinement the final asset requires.

Understand Current API Pricing

OpenAI's current model pages list token-based pricing for both GPT-Image-2.5 models. The published rates are $5 per million text input tokens, $8 per million image input tokens, and $30 per million image output tokens for both Flare and Sunburst.

Those numbers do not translate directly into one fixed price per image because the amount of image output and the input used by an editing request can vary. Image size and quality can therefore affect the amount of processing involved. Before launching a high-volume generator, monitor actual usage and calculate the cost from your application's real requests rather than assuming every generation has the same cost.

Keep API Keys Out of the Browser

A common mistake is placing the API key inside JavaScript that runs in a user's browser. Anyone who can inspect that application can potentially recover the credential and send requests against your account. The safer architecture is to send the browser request to your own backend, have the backend authenticate with OpenAI, and return only the generated image data or a controlled application response.

This also gives your server a place to enforce image-generation limits. For example, you can require a logged-in user, limit the number of generations per hour, restrict maximum image dimensions, and record which model and quality level were requested.

Handle Failed Requests

Image generation should be treated as a network operation that can fail. Your application should catch API errors, validate user input, avoid retrying requests indefinitely, and show a useful message when generation cannot be completed. If you automatically retry, use a bounded retry strategy so a temporary problem does not turn into a large number of duplicate requests.

from openai import OpenAI

client = OpenAI()

try:
    result = client.images.generate(
        model="gpt-image-2.5-flare",
        prompt="A clean futuristic AI workstation",
        size="1536x864",
        quality="medium",
    )
except Exception as error:
    print(f"Image generation failed: {error}")

For production code, catch the specific OpenAI exception types exposed by your installed SDK rather than using a broad Exception handler everywhere. Log the request metadata you need for debugging, but never write API credentials into application logs.

Build a Practical Image Workflow

A useful production pipeline can separate generation into three stages. First, the user supplies a prompt or reference image. Second, your backend selects the appropriate model, dimensions, quality, and safety settings. Third, the application stores the resulting image and its metadata so it can be displayed, edited, or regenerated later.

1. Validate: Check the prompt, image input, dimensions, and user permissions.
2. Select: Choose Flare for faster everyday generation or Sunburst for precision-focused editing.
3. Generate: Send the request through your protected backend.
4. Store: Save the decoded image using a generated filename rather than user-controlled file paths.
5. Review: Let the user approve or request an edit before publishing.

This structure is more useful than treating image generation as a single function call because it gives the application control over cost, authentication, storage, and repeated editing.

What to Build Next

GPT-Image-2.5 is particularly suitable for applications where image creation and editing are part of a larger workflow. An e-commerce tool could generate alternate product scenes, a publishing system could create article thumbnails, and a design application could let users modify selected elements while preserving the rest of a composition. OpenAI's current API exposes both models through image generation, while Sunburst also supports the image-edit endpoint for editing-focused workflows.

Start with one controlled workflow rather than building a general-purpose image editor immediately. Once generation, file handling, authentication, and usage tracking are working reliably, add reference-image editing and model selection. That gives you a manageable path from a simple API experiment to an AI image feature that can operate inside a real application.