GPT Image 2 API Guide for Generation and Editing

Updated October 28, 2026: GPT Image 2.5 has been available on WaveSpeedAI since September 9, 2026. Choose Flare Text-to-Image, Flare Edit, Sunburst Text-to-Image, or Sunburst Edit. Each endpoint supports five quality levels; check its current schema before use. GPT Image 2 remains available as described below.

I shipped a small product feature last week that needed image generation behind a button. Two days into the build, I realized the integration choices I made on day one were going to define how much pain I’d carry for the next six months. That’s the part nobody warns you about with the GPT Image 2 API. The hello-world is easy. The production posture is where it gets interesting.

I’m Dora. I write work notes after I ship things, not before. This is what I learned wiring OpenAI’s gpt-image-2 into a real product, and what I’d tell another developer or AI engineering team to think about before the first request goes out.

What You Need Before Using GPT Image 2 API

Model access, endpoints, and key docs

GPT Image 2 launched on April 21, 2026. The model ID is gpt-image-2. Before your first call you may need to complete API Organization Verification in the developer console.

You have three surfaces to choose from. The Image API exposes two endpoints: images.generate for text-to-image and images.edit for modifying existing images with a prompt and optional mask. The third surface is the Responses API, which exposes image generation as a built-in tool for conversational or multi-step flows.

Pick by job, not by novelty. If your product is “user types prompt, gets image,” use the Image API. If your product is “user has a back-and-forth conversation that sometimes produces images,” use the Responses API. Mixing them because one looks fancier than the other is a maintenance trap.

What GPT Image 2 supports today

Two things to internalize early.

Transparent backgrounds are available for GPT Image 2 in preview, rather than being universally unavailable. If that feature matters to your product, test background="transparent" with PNG or WebP on your chosen route before promising it to users. The current Images API reference distinguishes this preview support from the GPT Image 2.5 models.

Input fidelity is locked. The input_fidelity parameter exists on older models, but GPT Image 2 processes image inputs at high fidelity automatically. Omit the parameter. The cost implication: edit requests with reference images can consume more input tokens than you might expect from a GPT Image 1 workflow.

How to Generate Images with GPT Image 2

Basic request structure and output choices

A generation request takes a prompt and can specify size, quality, and output format. Format defaults to PNG; you can request JPEG or WebP, and JPEG is faster than PNG when latency matters. GPT Image 2 accepts presets or custom dimensions, provided both edges are multiples of 16, neither edge exceeds 3840px, the aspect ratio is at most 3:1, and the pixel count is between 655,360 and 8,294,400.

Here is the direct OpenAI call I would start with. Install the openai Python package, set OPENAI_API_KEY, then run it. The returned image is base64 data in response.data[0].b64_json, so the final line writes the actual PNG:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()
response = client.images.generate(
    model="gpt-image-2",
    prompt="A clean product photo of a blue ceramic mug on a white table",
    size="1024x1024",
    quality="medium",
    output_format="png",
    n=1,
)

Path("generated.png").write_bytes(
    base64.b64decode(response.data[0].b64_json)
)

The n parameter lets you generate multiple images in one request. Useful when you need variations to compare. Less useful when you’re paying for every output.

Managing size, quality, and workflow trade-offs

This is where most teams burn money without realizing it. GPT Image 2 is billed per token, not at one universal per-image price. At the standard rate checked on October 28, 2026, image input is $8 per 1M tokens, image output is $30 per 1M tokens, and text input is $5 per 1M tokens. Batch rates are lower for eligible batch work. Cached input pricing applies to the image-generation tool in the Responses API, not to direct Images API requests.

What that means in practical numbers: at 1024×1024, OpenAI’s calculator estimates roughly $0.006 for low quality, $0.053 for medium, and $0.211 for high. At 1024×1536, the estimates are $0.005, $0.041, and $0.165. Those are image-output estimates, not complete request totals. Add prompt input and, for edits, reference-image input.

So the trade-off question isn’t which quality looks best. It’s: at my volume, what’s the cost difference between medium and high, and does my user actually perceive it? For a thumbnail surface, low quality may be enough. For a hero image users will stare at, high may earn its price. I picked medium as the default and exposed high as an opt-in. In my projection, that single decision changed my monthly bill by about 4x; it was a planning estimate, not a measured billing result.

How Image Editing Works

Input requirements and common edit scenarios

The edits endpoint takes an image, an optional mask, and a prompt describing the change. Pass one image to edit it. Pass multiple images to combine subjects, styles, or references into one output. A mask indicates the area to change; don’t treat it as a guarantee that every unmasked pixel will remain identical. The source image and mask must meet the edit endpoint’s file requirements, and the mask needs an alpha channel.

This second example uses generated.png from the generation example. It sends a direct OpenAI edit request and saves the returned base64 image:

import base64
from pathlib import Path
from openai import OpenAI

client = OpenAI()

with open("generated.png", "rb") as source:
    response = client.images.edit(
        model="gpt-image-2",
        image=source,
        prompt="Change only the blue mug to matte red ceramic; keep the setting",
        size="1024x1024",
        quality="medium",
        output_format="png",
    )

Path("edited.png").write_bytes(
    base64.b64decode(response.data[0].b64_json)
)

Common edits I’ve validated in my own workflow, without a published test set: background swaps on product photos, object removal, style transfer between references, and text translation inside an image. If the job only requires isolating a subject before placing it on a new background, a free background remover is often simpler than a full generative edit. For simpler cleanup, a free image cleanup tool may be faster than building an API edit workflow.

The character-consistency claim—same character across multiple generated scenes—works for me on simple subjects. It gets less reliable as scene complexity grows. That’s an observation from my work, not a consistency benchmark.

Mistakes that increase cost or reduce consistency

Sending oversized inputs. GPT Image 2 processes image inputs at high fidelity. Downscale a reference if the task does not need its original detail, then compare the result before making that a production rule.

Vague edit prompts. “Make it better” produces unpredictable changes and often costs you a retry. “Change the red hat to light blue velvet; keep everything else” gives the model a narrower job.

Using n=4 by default. Asking for four options sounds harmless until you realize you’ll pay for four outputs when you may use one.

Treating edits like generations for cost estimation. Reference images add image-input tokens. Plan that into your pricing model before launch.

Production Considerations for Teams

Retries, moderation, and operational guardrails

Three things that are not optional in production.

Retries with exponential backoff. Complex image requests can take up to two minutes, and you may hit rate limits. OpenAI’s rate-limit guidance says to honor Retry-After when present and use backoff with jitter for transient limits. Don’t retry an invalid parameter, a quota problem, or a blocked request unchanged. Also check your SDK’s own retry settings before adding another retry loop around it.

Moderation, in two layers. The image endpoint has a moderation parameter (auto is the default; low is less restrictive, not unfiltered). For user-submitted prompts, you can also call the free omni-moderation-latest endpoint before generation. It accepts text and images, but its categories and coverage have limits; it does not replace your application’s review rules.

Logging at the right grain. Log model ID, size, quality, latency, request ID, retry count, moderation outcome, and the cost you later reconcile against billing. Record token usage when the response actually provides it; don’t assume every GPT Image 2 Images API response exposes the token fields you want. In production, consider the dated snapshot gpt-image-2-2026-04-21 if you need to hold behavior steady. The production best practices guide covers the broader operational layer.

When to keep direct integration simple vs add a platform layer

This is the question I sat with longest.

Direct OpenAI integration is the right answer when your product uses one image model, your team has API ops experience, and your traffic is predictable enough that owning rate limits and first-party billing matters more than convenience.

A platform layer—and yes, I work on one at WaveSpeedAI—earns its place in different situations. You’re routing across multiple image models (GPT Image 2 for typography, another model for a different image task, and perhaps another for video). Teams comparing newer image-generation options can also evaluate the Seedream 5 image API as part of that stack. You want pricing shown for the specific endpoint and settings before submitting a job, when calculable, rather than estimating OpenAI token consumption yourself. You want one integration surface across models.

Neither answer is universal. Count how many model providers your product calls today, consider how that may change, and ask whether you want to maintain those integrations yourself.

What Changes When You Call WaveSpeedAI Instead

The two code examples above are direct OpenAI calls: you receive base64 image data and save it. WaveSpeedAI’s GPT Image 2 route uses an asynchronous prediction: submit a task, receive data.id, poll that ID, then download the URL in data.outputs when its status becomes completed. The field names and flow come from WaveSpeedAI’s task submission and result retrieval documentation.

For this third example, install requests and set WAVESPEED_API_KEY. It uses the GPT Image 2 text-to-image route, whose parameters are aspect_ratio and resolution, rather than OpenAI’s size. It saves the finished image as wavespeed.png:

import os
import time
from pathlib import Path
import requests

base = "https://api.wavespeed.ai/api/v3"
headers = {"Authorization": f"Bearer {os.environ['WAVESPEED_API_KEY']}"}

submitted = requests.post(
    f"{base}/openai/gpt-image-2/text-to-image",
    headers=headers,
    json={
        "prompt": "A clean product photo of a blue ceramic mug on a white table",
        "aspect_ratio": "1:1",
        "resolution": "1k",
        "quality": "medium",
        "output_format": "png",
    },
    timeout=(10, 60),
)
submitted.raise_for_status()
task_id = submitted.json()["data"]["id"]

while True:
    try:
        polled = requests.get(
            f"{base}/predictions/{task_id}/result",
            headers=headers,
            timeout=30,
        )
    except requests.RequestException:
        time.sleep(2)
        continue

    if polled.status_code in {429, 500, 502, 503, 504}:
        time.sleep(2)
        continue

    polled.raise_for_status()
    result = polled.json()["data"]

    if result["status"] == "completed":
        image = requests.get(result["outputs"][0], timeout=60)
        image.raise_for_status()
        Path("wavespeed.png").write_bytes(image.content)
        break

    if result["status"] in {"failed", "cancelled", "timeout", "deleted"}:
        raise RuntimeError(result.get("error") or result["status"])

    time.sleep(2)

One operational trap: if a WaveSpeed submit request times out before you receive the ID, don’t blindly submit the same job again. The first task may have been created. Check task history before resubmitting. Once you have an ID, retry result retrieval, not task creation. A 401 points to authentication, a 400 to the request or model schema, and a 429 to rate limits; those need different fixes.

FAQ

Which endpoint should developers use for GPT Image 2?

Use images.generate for text-to-image, images.edit for modifying an existing image with a prompt and optional mask, and the Responses API image tool when generation belongs inside a multi-turn conversation. On WaveSpeedAI, choose the separate text-to-image or edit route and follow its prediction flow.

Does GPT Image 2 support image edits?

Yes. The images.edit endpoint accepts one or more reference images plus a prompt and supports an optional mask. GPT Image 2 processes image inputs at high fidelity automatically; omit input_fidelity.

What should teams log and monitor in production?

At minimum: model or snapshot ID, size, quality, latency, request ID, retry count, moderation outcome, and an estimated cost reconciled against billing. Record input and output token counts where the selected API actually returns them.

When does a simple API integration stop being enough?

When you’re calling more than one image provider, when failure handling needs cross-provider fallback, or when your team wants to manage models through one API. Below those thresholds, direct integration may be simpler.

How do I keep prompt-injection and unsafe outputs from leaking into production?

Moderate user prompts, keep the image API’s moderation setting appropriate for your product, and review outputs where errors would matter. If a Responses workflow also reads untrusted text or images, treat instructions inside that material as untrusted; moderation alone does not solve prompt injection. Follow OpenAI’s safety best practices for review and testing before launch.

Conclusion

The GPT Image 2 API isn’t hard to wire up. The first request takes an afternoon. The decisions that matter—quality defaults, edit cost modeling, moderation, retry behavior, and whether to add a platform layer—are the ones that quietly compound for months after you ship. Pick them deliberately. Run the small pilot first. The rest follows.

Previous posts: