107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
# 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
|
|
```
|
|
|