GPT Image 2.5 | API 文件

# GPT Image 2.5

Generate images with Flare or edit reference images with Sunburst.

POST https://api.apihop.ai/openai/v1/images/generations

Use `gpt-image-2.5-flare` for fast image generation or `gpt-image-2.5-sunburst` for precise editing. Check `GET https://api.apihop.ai/v1/models` for availability with your API key.

## Request

```http
POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}
```

| Parameter | Values |
| --- | --- |
| `model` | Required: `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst` |
| `prompt` | Required text describing the image or edit |
| `n` | Integer from 1 to 4; default 1 |
| `size` | `auto`, aspect ratio, or pixel dimensions such as `1600x1200` |
| `resolution` | `1k` (default), `2k`, `4k`; ignored for exact pixel sizes |
| `quality` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (default) |
| `image_urls` | Up to 16 publicly accessible HTTP(S) image URLs |
| `output_format` | `png` (default), `jpeg`, `webp` |
| `output_compression` | Integer from 0 to 100 for JPEG or WebP |
| `background` | `auto`, `opaque`, `transparent`; transparent requires PNG or WebP |
| `moderation` | `low` (default), `auto` |
| `stream` | `false` (default) for JSON, `true` for SSE completion events |

Supported aspect ratios: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3`. Exact pixel dimensions must be multiples of 16, have no side above 3840 pixels, an aspect ratio at most 3:1, and 655,360 to 8,294,400 total pixels. For example, square `4k` output is 2880x2880, not 4096x4096.

## Reference Images

```json
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

References use this JSON generation endpoint. Upload local images to your own storage first. Base64 data URIs, multipart uploads, masks, and a separate `/images/edits` endpoint are outside this model's public contract.

## Response

The HTTP connection waits for completion; clients do not poll an upstream task. JSON responses include final image URLs and available token usage:

```json
{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}
```

With `stream: true`, wait for `image_generation.completed` and `[DONE]` on the same connection. Partial image previews are not guaranteed.

## Pricing

Billing uses actual text input, cached text input, image input, cached image input, and image output tokens. Both variants have the same token prices. The model catalog shows your current price and the separate OpenAI reference price. An image is not a fixed-price unit: prompt length, references, size, quality, and count affect the total. A temporary reservation is reconciled after completion. Choosing an explicit quality makes expected usage clearer.

Invalid parameters return 400; authentication failures return 401; insufficient balance returns 402. An unavailable model returns 404, rate limits return 429, and generation failures return 5xx. Do not automatically resubmit a request whose completion status is unknown.

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for error codes, streaming failures, and retry boundaries.

使用 gpt-image-2.5-flare 快速生成圖像，或使用 gpt-image-2.5-sunburst 進行精準編輯。請透過 GET https://api.apihop.ai/v1/models 確認您的金鑰是否可用。

請求

http

POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

json

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}

參數	值
`model`	必填：`gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`
`prompt`	必填文字，描述圖像或編輯內容
`n`	1 至 4 的整數，預設為 1
`size`	`auto`、長寬比或像 `1600x1200` 這樣的像素尺寸
`resolution`	`1k`（預設）、`2k`、`4k`；指定精確像素尺寸時忽略
`quality`	`low`、`medium`、`high`、`xhigh`、`max`、`auto`（預設）
`image_urls`	最多 16 個可公開存取的 HTTP(S) 圖像網址
`output_format`	`png`（預設）、`jpeg`、`webp`
`output_compression`	適用 JPEG 或 WebP，0 至 100 的整數
`background`	`auto`、`opaque`、`transparent`；透明背景需要 PNG 或 WebP
`moderation`	`low`（預設）、`auto`
`stream`	`false`（預設）使用 JSON，`true` 使用 SSE 完成事件

支援的長寬比：1:1、3:2、2:3、4:3、3:4、5:4、4:5、16:9、9:16、2:1、1:2、21:9、9:21、3:1、1:3。精確像素尺寸必須是 16 的倍數，任一邊不得超過 3840 像素，長寬比不得超過 3:1，總像素數必須介於 655,360 至 8,294,400。例如正方形 4k 輸出為 2880x2880，而非 4096x4096。

參考圖像

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

參考圖像使用同一個 JSON 生成端點。請先將本機圖像上傳至您自己的儲存空間。Base64 資料 URI、multipart 上傳、遮罩及獨立的 /images/edits 端點不屬於此模型的公開契約。

回應

HTTP 連線會等待完成，客戶端不必輪詢上游任務。JSON 回應包含最終圖像網址及可用的 token 用量：

json

{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}

設定 stream: true 時，請在同一連線中等待 image_generation.completed 與 [DONE]。不保證提供局部圖像預覽。

定價

計費依實際文字輸入、快取文字輸入、圖像輸入、快取圖像輸入及圖像輸出 token 計算。兩個版本使用相同的 token 價格。模型目錄會顯示您目前的價格，並另外列出 OpenAI 參考價格。一張圖像不是固定價格單位：提示詞長度、參考圖像、尺寸、品質及數量都會影響總額。暫時預留款會在完成後結算。明確指定品質可讓預期用量更清楚。

參數無效回傳 400、驗證失敗回傳 401、餘額不足回傳 402。模型不可用回傳 404、速率限制回傳 429、生成失敗回傳 5xx。完成狀態不明的請求請勿自動重新提交。

錯誤代碼、串流失敗與重試邊界，請見錯誤代碼與疑難排解。