# 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

```text
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

```json
{
  "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

```bash
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:

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