GPT Image 2 API Reference For sub2api

Source links:

https://developers.openai.com/api/docs/models/gpt-image-2
https://developers.openai.com/api/docs/guides/image-generation
https://developers.openai.com/api/reference/resources/images
Repository docs: apis/sub2api/gpt-image-2.zh.md and apis/sub2api/gpt-image-2.en.md

Endpoints

POST /v1/images/generations
POST /v1/images/edits
POST /v1/responses  # image_generation tool with a text/agent model

/v1/models may only list Codex/text models in this deployment. That does not mean /v1/images/generations cannot accept gpt-image-2.

Generation Parameters

Parameter	Values	Notes
`model`	`gpt-image-2`, `gpt-image-2-2026-04-21`	Required for Images API.
`prompt`	string	Required. Be concrete about subject, composition, style, lighting, and safety constraints.
`n`	`1-10`	Prefer `1` for production retries and billing attribution.
`size`	`auto` or valid `WxH`	Common: `1024x1024`, `1536x1024`, `1024x1536`, `3840x2160`.
`quality`	`low`, `medium`, `high`, `auto`	Use `low` for drafts, `medium` for normal, `high` for final.
`output_format`	`png`, `jpeg`, `webp`	`jpeg` is usually faster than `png`.
`output_compression`	`0-100`	Applies to `jpeg` and `webp`.
`background`	`auto`, `opaque`	`gpt-image-2` does not support `transparent`.
`moderation`	`auto`, `low`	Changes filter strictness but does not bypass policy.
`stream`	boolean	Enables SSE image events.
`partial_images`	`0-3`	Streaming only; each partial image adds output token cost.
`user`	string	End-user identifier for abuse monitoring.

Size Constraints

Maximum edge length: 3840px.
Both edges must be multiples of 16px.
Long edge to short edge ratio must be at most 3:1.
Total pixels must be between 655360 and 8294400.
Outputs larger than 2560x1440 should be treated as high-latency experimental outputs.

Edit Notes

Use multipart form data.
Send reference images as image[].
Optional mask must match input image format and dimensions, be under 50MB, and include an alpha channel.
Omit input_fidelity for gpt-image-2.

Response Shape

{
  "data": [
    {
      "b64_json": "...",
      "revised_prompt": "..."
    }
  ],
  "model": "gpt-image-2",
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "usage": {
    "input_tokens": 43,
    "output_tokens": 196,
    "total_tokens": 239
  }
}

Always decode data[0].b64_json unless streaming.

Production Dispatch

Prefer plus/team/pro upstream OpenAI OAuth accounts for image workloads.
Set client timeout to 120s for normal images and 300s for 4K.
Retry only transient network/5xx failures with low retry counts.
Do not retry policy or validation errors without changing the prompt or params.
Log usage, latency, size, quality, output format, account ID, API key ID, and request ID.

Valid curl Template

curl -sS "$BASE_URL/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A premium product poster for an AI service",
    "size": "1536x1024",
    "quality": "medium",
    "output_format": "png",
    "n": 1
  }' > image.json

Decode:

jq -r '.data[0].b64_json' image.json | base64 --decode > image.png

3.4 KiB Raw Blame History