# OpenAI Images API (/v1/images/*)

Status: POST /v1/images/generations DOCUMENTED + LIVE_VERIFIED · POST /v1/images/edits DOCUMENTED (UNVERIFIED, paid) · POST /v1/images/variations LEGACY + RETIRED (live 404) · DALL·E 2/3 RETIRED (removed 2026-05-12) · gpt-image-1 / 1-mini / 1.5 / chatgpt-image-latest DEPRECATED (shutdown 2026-10-23 / 2026-12-01). Sources: Images reference · Generation streaming events · Edit streaming events · Image generation guide · Pricing · Deprecations · model pages gpt-image-*, chatgpt-image-latest, dall-e-3 · OpenAPI CreateImageRequest, CreateImageEditRequest, CreateImageVariationRequest, ImageGenStreamEvent, ImageEditStreamEvent. Last verified: 2026-09-18 (live calls logged in reports/live-requests.jsonl, raw in tmp-live/media-agent-batch2.json). Machine-readable: generated/fragments/endpoints/openai-images-video-embeddings-moderation.json, parameters/openai-images.json, streaming-events/openai-images.json, objects/openai-media-objects.json, prices/openai-media.json.

The Image API is the direct way to generate/edit images. The image_generation tool of the Responses API (multi-turn editing, file IDs, mainline model + tool.model) is documented by the tools agent — see docs/tools/.

# Endpoints

SDKs: Python client.images.generate / edit / create_variation; Node client.images.generate / edit / createVariation. Batch API: gpt-image-2, 1.5, 1, 1-mini, chatgpt-image-latest (not 2.5 per model pages).

# Model matrix

Live /v1/models (2026-09-18) lists all GPT image ids above (incl. dated snapshots) but no dall-e-*.

Arbitrary sizes (gpt-image-2 / 2.5): WIDTHxHEIGHT, both multiples of 16, aspect ratio between 1:3 and 3:1, max edge 3840 px, total pixels 655,360–8,294,400 (4K); > 2560×1440 is experimental. Popular: 1024², 1536×1024, 1024×1536, 2048², 2048×1152, 3840×2160, 2160×3840. Older GPT image models reject anything else — live: size=123x456 on gpt-image-1-mini → 400 {type: image_generation_user_error, param: size, code: invalid_value, message: "Invalid size '123x456'. Supported sizes are 1024x1024, 1024x1536, 1536x1024, and auto."}.

# Parameters (generations)

# Edits: inputs, masks, fidelity

• Inputs: multipart image (single) or repeated image[] (≤ 16 images, png/webp/jpg, each < 50 MB for GPT image); JSON body alternative images: [{file_id | image_url}] (URL or base64 data URL). dall-e-2: one square PNG < 4 MB.
• Mask: PNG with alpha channel; fully transparent pixels = area to edit; same size/format as the first image; applied to the first image only. With GPT Image, masking is prompt-guided (not pixel-exact). JSON form: mask: {file_id | image_url}.
• input_fidelity low (default) | high: preserve details/faces of inputs. gpt-image-1, 1.5, chatgpt-image-latest, 2.5 ✓; gpt-image-1-mini ✗; gpt-image-2 always high (omit the param; more input tokens on edits). Changelog notes a fixed bug where 1.5/chatgpt-image-latest ignored low.
• Spec default model for edits = gpt-image-1.5. Same quality/size/background/output_*/moderation/stream/partial_images/n/user semantics as generations.

# Response object (ImagesResponse)

{"created": 1789782224, "background": "opaque", "output_format": "jpeg", "quality": "low", "size": "1024x1024",
 "data": [{"b64_json": "<base64 jpeg>", "generation_id": "<opaque id>"}],
 "usage": {"input_tokens": 10, "input_tokens_details": {"image_tokens": 0, "text_tokens": 10},
           "output_tokens": 272, "output_tokens_details": {"image_tokens": 272, "text_tokens": 0}, "total_tokens": 282}}

Live (gpt-image-1-mini, low, 1024², jpeg, 5.7 s, 39 383 bytes). generation_id in each data[] item is undocumented (LIVE_DISCOVERED). url/revised_prompt were DALL·E-only. usage is present for all GPT image models although the reference text still says "gpt-image-1 only".

# Streaming (GPT image models only)

stream: true → SSE stream of event:/data: pairs, then connection close. Events (generated/fragments/streaming-events/openai-images.json):

Streaming not exercised live (UNVERIFIED; cost).

# Pricing pointers (USD, standard tier; batch = 50 %)

Legacy output-token counts (pre-gpt-image-2): low 272 / 408 / 400 tokens, medium 1056 / 1584 / 1568, high 4160 / 6240 / 6208 for 1024² / 1024×1536 / 1536×1024 → per-image tables on the model pages (e.g. gpt-image-1-mini low 1024² ≈ $0.005; 1.5 high portrait $0.20; gpt-image-2 low 1024² $0.006, high $0.211). Our live call: 272 output tokens × $8/M + 10 text tokens ≈ $0.0022. gpt-image-2/2.5 token counts vary by size/quality (use usage; the guide's calculator does not cover 2.5). Each partial image adds 100 output tokens. Rate limits (all GPT image, model pages): Tier 1 100k TPM / 5 IPM … Tier 5 8M TPM / 250 IPM.

# Limits and errors

• Latency up to ~2 min for complex prompts; text rendering, consistency and layout precision remain weak spots (guide).
• All prompts/images are filtered per usage policies; moderation: "low" relaxes filtering. Org verification may be required for GPT image models.
• User-correctable failures: error.type = "image_generation_user_error" with stable error.code (e.g. invalid_value) — do not retry unchanged. Unknown params → invalid_request_error / unknown_parameter.
• Data residency: /v1/images/generations and /edits are available on all regional endpoints (gpt-image-2/2.5/1/1.5/1-mini).

# Examples and tests

examples/openai/images/ (generate.sh|py|ts, edit.sh UNVERIFIED, stream.py UNVERIFIED) · tests/openai/test_images.py (marker run_image_tests; the validation-error test is free and unmarked).