GPT Image 2.5 is exposed to developers through OpenAI’s API, supporting both generation and editing tasks.
You can use the traditional Images API, or use the image generation tool inside the Responses API for conversational workflows.
This article explains the two paths, key parameters, authentication, and getting started to help you plan an integration.
API overview
OpenAI offers two paths for GPT Image 2.5: the Images API and the Responses API, which share the same model capabilities.
The Images API handles standalone generation and editing, while the Responses API treats generation as a tool inside a conversation.
-
Images API for standalone generation and editing
-
Responses API for conversational, multi-step flows
-
Both support GPT Image 2.5 models
-
Images return as base64 or a temporary URL
-
Billing depends on model, quality, and size
-
Organization verification is required
Images API vs Responses API
The Images API exposes generate and edit endpoints with a simple request shape, ideal for batch and direct calls.
The Responses API generates images through the image_generation tool, supporting multi-turn refinement and in-context editing.
-
The generate endpoint handles text-to-image
-
The edit endpoint handles image editing
-
The image_generation tool drives conversational generation
-
The action parameter distinguishes generate and edit
-
Multi-turn editing uses previous_response_id
-
Choose the path that fits your application
Key parameters
Both paths control output through prompt, model, quality, and size, and these values closely affect cost.
Understanding quality tiers, size combinations, and output format is the key to controlling results and cost.
-
prompt describes what to generate
-
model selects a specific model
-
quality controls the image quality tier
-
size sets the output size and aspect ratio
-
background controls transparency
-
output_format selects the image format
Authentication and setup
Calling the API requires an API key, and using GPT Image models usually requires organization verification first.
Keys should be managed through environment variables, never written into code or committed to a repository.
-
Inject API keys through environment variables
-
Complete organization verification first
-
Apply least-privilege key management
-
Never expose keys in the frontend
-
Isolate keys per project
-
Rotate and audit keys regularly
Getting started
Start with a minimal request to confirm generation works, then add quality, size, and editing parameters step by step.
Before integrating, read the docs to understand rate limits, billing, and content safety policies.
-
Request and configure an API key
-
Run a minimal request for the first image
-
Parse the response and save the image
-
Add quality and size parameters gradually
-
Understand rate limits and retries
-
Validate in a test environment first
A worked example: the smallest generation call
Start with the smallest request that proves the path end to end, then add parameters one at a time so you know which one changed the result.
Put the key in the environment before anything else:
export OPENAI_API_KEY="sk-..."Then make one generate call and decode the payload:
from openai import OpenAI
import base64
from pathlib import Path
client = OpenAI()
result = client.images.generate(
prompt="A wide shot of a family looking up at a vast cylindrical habitat, retro-futurist illustration, teal and cream palette.",
quality="high",
size="1024x1024",
)
Path("out.png").write_bytes(base64.b64decode(result.data[0].b64_json))Editing reuses the same client and adds a reference image:
from openai import OpenAI
import base64
from pathlib import Path
client = OpenAI()
edited = client.images.edit(
image=open("out.png", "rb"),
prompt="Keep the composition. Change the palette to warm amber and deep green.",
)
Path("edited.png").write_bytes(base64.b64decode(edited.data[0].b64_json))Two things to notice. The response carries image bytes rather than a link, so you persist them yourself; and the edit call describes only the change, because the reference image already carries everything else. Parameter names and the values each accepts move independently of this page, so check them against the official API reference before you ship. For the workflow behind a good edit instruction, see the comment editing guide.
Choosing between the two paths
The two paths share models, so decide by request shape rather than by capability.
| Images API | Responses API | |
|---|---|---|
| Request shape | One endpoint per action | One conversation carrying tools |
| Fits | Batch jobs and single-shot generation | Interactive refinement |
| Multi-turn editing | You resend the prompt and the image | The response carries the context |
| Editing input | A dedicated edit endpoint | An instruction inside the conversation |
| Failure to plan for | Retry logic per request | Context growth across turns |
If your users iterate on one image, the Responses API saves you from rebuilding state every turn. If you generate at volume with nobody in the loop, the Images API is the simpler contract. The models themselves are covered in the GPT Image 2.5 overview.
Frequently asked questions
Where does the image come back?
As base64 data in the response, or as a temporary URL depending on how you call it. Persist the bytes yourself rather than storing the URL, because the URL expires.
Do I need organization verification?
For the image models, yes. Complete it before the first call, because a missing entitlement otherwise surfaces as a generic bad request.
How do I keep a subject consistent between calls?
Repeat the identity description verbatim in every prompt, or send a reference image to the edit endpoint. Both approaches are worked through in the templates guide.
Which parameters move the cost the most?
Quality and size. Fix the composition at a low tier, then re-run the same prompt at the tier you intend to ship rather than experimenting at the top tier.
The GPT Image 2.5 API spans from standalone calls to conversational integration; the right path depends on your application.
Understanding parameters, authentication, and billing is the basis for controlling results and cost.
Before development, verify model availability, parameter values, and limits against the official docs.