# GPT 图像生成
> 文生图、参考图编辑、蒙版重绘
> 参考图最多 16 张，一次生成最多 4 张
> 画质分 low / medium / high / xhigh / max 五档
`POST /v1/images/generations`
## 认证
- `Authorization` (string / 必填) — 所有接口均使用 Bearer Token 进行认证。 获取 API Key：[访问控制台](https://api.oairoute.com/keys) 创建。 请求时在请求头中添加： ```http Authorization: Bearer YOUR_OAIRoute_KEY ```
## 请求结构
请求体是平铺的 JSON，创作字段与输出字段都在顶层，没有 `content` 数组包装。
## 支持的场景
| 场景 | 字段组合 |
|---|---|
| 文生图 | `prompt` |
| 单图编辑 | `prompt` + `image`（1 张） |
| 多图参考 | `prompt` + `image`（2 到 16 张） |
| 蒙版重绘 | `prompt` + `image` + `mask_url` |
| 固定画布 | `size` 写精确像素 |
传入 `image` 后自动进入编辑模式，不需要额外参数切换。`mask_url` 单独传无效。
## 请求参数
> **Note:** 
> 提交后同步返回图片本身，不返回任务 ID。图片在 `data[].b64_json`，是 Base64 字符串，客户端解码后落盘。需要动图或矢量输出见 [GPT Image 2.6](gpt-2-6.html)。
- `model` (string / 必填) — 取值 `gpt-image-2.5-flare` 或 `gpt-image-2.5-sunburst`。 两者单价相同，`flare` 偏速度与批量，`sunburst` 偏编辑精度与多轮打磨。
- `prompt` (string / 必填) — 画面描述，中英文均可。建议写清主体、场景、构图、风格、光线，以及哪些必须保留、哪些需要改动。
- `size` (string / 可选) — 默认 `auto`。 可写宽高比 `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`，也可写精确像素如 `1600x1200`。 图生图时建议省略，由模型按输入图比例推算。
- `resolution` (string / 可选) — 输出档位，取值 `1k`（默认）、`2k`、`4k`。 与比例形式的 `size` 配合决定像素；`size` 写精确像素时该字段失效。
- `quality` (string / 可选) — 画质档位，取值 `low`、`medium`、`high`、`xhigh`、`max`、`auto`，默认 `auto`。 `auto` 先按最高档预扣，完成后按实际 token 结算。
- `n` (integer / 可选) — 生成张数，取值 1 到 4，默认 `1`。必须传数字，不能传字符串。
- `image` (string | string[] / 可选) — 参考图，最多 16 张公网地址。 传入即进入编辑模式：第一张是主体，其余作为场景、光线或风格参考。
- `mask_url` (string / 可选) — 蒙版，仅配合 `image` 使用，只作用于第一张参考图。 透明像素表示可重绘区域。像素尺寸必须与第一张参考图完全一致，而不是与输出尺寸一致。
- `output_format` (string / 可选) — 取值 `png`（默认）、`jpeg`、`webp`。PNG 与 WebP 支持透明背景。
- `output_compression` (integer / 可选) — 压缩比，取值 0 到 100，仅对 jpeg 与 webp 生效。
- `background` (string / 可选) — 取值 `transparent`、`opaque`、`auto`。 `transparent` 与 jpeg 不能同时使用。
- `moderation` (string / 可选) — 内容审核档位，取值 `auto`、`low`，默认 `low`。
## 尺寸约束
精确像素时：宽高都必须能被 16 整除，单边不超过 3840，长短边比例不超过 3:1，总像素在 655360 到 8294400 之间。
比例形式与 `resolution` 组合出像素，例如 `1:1` 在 1k / 2k / 4k 下分别是 1024×1024、2048×2048、2880×2880。
超过 2560×1440 的输出稳定性会下降，属于实验范围。
## 响应
同步返回，与 OpenAI Images API 一致。返回体里只有 `b64_json` 与 `generation_id`，**没有图片 URL**；请求会阻塞到图片生成完成，没有任务 ID，也不需要轮询。
```json
{
  "created": 1763088302,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU…",
      "generation_id": "a3b37aae-9c63-46f1-acb5-ac6cf174bdb4"
    }
  ],
  "size": "1024x1024",
  "output_format": "png",
  "quality": "high",
  "background": "opaque",
  "usage": {
    "input_tokens": 32,
    "output_tokens": 4160,
    "total_tokens": 4192,
    "input_tokens_details": { "text_tokens": 32, "image_tokens": 0 },
    "output_tokens_details": { "text_tokens": 0, "image_tokens": 4160 }
  }
}
```
### 字段说明
- `created` (integer) — 生成完成时间，Unix 秒。
- `data` (array) — 每项对应一张输出图。
- `data[].b64_json` (string) — Base64 图片数据，解码后即 PNG / JPEG / WebP 文件。本接口不返回图片 URL，必须自己解码落盘。
- `data[].generation_id` (string) — 本次生成的唯一标识，可用于日志关联与排障。
- `data[].revised_prompt` (string / 可选) — 模型改写后的提示词，GPT Image 系列通常不返回。
- `size` (string) — 实际输出尺寸，如 `1536x1024`。
- `output_format` (string) — 实际输出格式。
- `quality` (string) — 实际使用的画质档位。
- `background` (string / 可选) — `transparent` 或 `opaque`。
- `usage` (object) — 计费用量，含 `input_tokens`、`output_tokens`、`total_tokens`，以及图片 / 文本分项。
> **Note:** 
> 生成是同步的，请求会阻塞到图片出完。普通尺寸通常几十秒，复杂提示词官方给出上限约 2 分钟，客户端超时建议设到 3 分钟以上。 WebP 与 JPEG 比 PNG 快，对延迟敏感时优先选这两种。
## 错误码
| HTTP | 含义 |
|---|---|
| 400 | 参数错误，type 为 invalid_request_error |
| 401 | Token 缺失或无效，type 为 authentication_error |
| 402 | 余额不足，type 为 payment_required |
| 429 | 触发限流 |
更多状态码与重试建议见[错误码与限流](../../support/errors.html)，常见报错的排查步骤见[常见问题](../../support/faq.html)。
## 支持的模型列表
| 模型 ID | 定位 | GIF / SVG |
|---|---|---|
| `gpt-image-2.6-flare` | 2.6 代，速度优先，适合批量与原型 | ✅ |
| `gpt-image-2.6-sunburst` | 2.6 代，细节优先，适合成品图与多轮打磨 | ✅ |
| `gpt-image-2.5-flare` | 速度优先，适合批量与原型 | — |
| `gpt-image-2.5-sunburst` | 编辑精度优先，适合成品图与多轮打磨 | — |
| `gpt-image-2` | 上一代主力，不支持 `xhigh` 与 `max` 档 | — |
| `gpt-image-1.5` | 轻量，出图快 | — |
| `gpt-image-1-mini` | 成本最低 | — |
`xhigh` 与 `max` 只有 2.5 及以后支持，传给 `gpt-image-2` 会返回 400，不会降档。`gif` 与 `svg` 只有 2.6 支持，参数细节见 [GPT Image 2.6](gpt-2-6.html)。
> **Note:** 完整模型目录（含价格、分辨率上限）可读取 `GET https://api.oairoute.com/api/pricing`；也可用 `GET /v1/models` 筛 `supported_endpoint_types` 含 `image-generation` 的条目。
## 使用示例
**文生图{Text to image}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-flare",
  "prompt": "清晨的山谷，薄雾缠绕树林，胶片质感，自然光",
  "size": "3:2",
  "resolution": "2k"
}'
```
**文生图{Text to image}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "gpt-image-2.5-flare",
  "prompt": "清晨的山谷，薄雾缠绕树林，胶片质感，自然光",
  "size": "3:2",
  "resolution": "2k"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**文生图{Text to image}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-image-2.5-flare",
  "prompt": "清晨的山谷，薄雾缠绕树林，胶片质感，自然光",
  "size": "3:2",
  "resolution": "2k"
}),
});
console.log(await res.json());
```
**200 文生图{Text to image}**
```
{
  "created": 1763088302,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU…",
      "generation_id": "a3b37aae-9c63-46f1-acb5-ac6cf174bdb4"
    }
  ],
  "size": "1024x1024",
  "output_format": "png",
  "quality": "high",
  "usage": { "input_tokens": 32, "output_tokens": 4160, "total_tokens": 4192 }
}
```
**参考图编辑{Reference edit}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "把沙发换成墨绿色布艺沙发，其余保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}'
```
**参考图编辑{Reference edit}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "gpt-image-2.5-sunburst",
  "prompt": "把沙发换成墨绿色布艺沙发，其余保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**参考图编辑{Reference edit}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-image-2.5-sunburst",
  "prompt": "把沙发换成墨绿色布艺沙发，其余保持不变",
  "image": [
    "https://example.com/room.jpg"
  ]
}),
});
console.log(await res.json());
```
**200 参考图编辑{Reference edit}**
```
{
  "created": 1763088302,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU…",
      "generation_id": "a3b37aae-9c63-46f1-acb5-ac6cf174bdb4"
    }
  ],
  "size": "1024x1024",
  "output_format": "png",
  "quality": "high",
  "usage": { "input_tokens": 32, "output_tokens": 4160, "total_tokens": 4192 }
}
```
**蒙版重绘{Masked redraw}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "把这块区域换成一只橘猫",
  "image": [
    "https://example.com/room.jpg"
  ],
  "mask_url": "https://example.com/room-mask.png"
}'
```
**蒙版重绘{Masked redraw}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "gpt-image-2.5-sunburst",
  "prompt": "把这块区域换成一只橘猫",
  "image": [
    "https://example.com/room.jpg"
  ],
  "mask_url": "https://example.com/room-mask.png"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**蒙版重绘{Masked redraw}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-image-2.5-sunburst",
  "prompt": "把这块区域换成一只橘猫",
  "image": [
    "https://example.com/room.jpg"
  ],
  "mask_url": "https://example.com/room-mask.png"
}),
});
console.log(await res.json());
```
**200 蒙版重绘{Masked redraw}**
```
{
  "created": 1763088302,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU…",
      "generation_id": "a3b37aae-9c63-46f1-acb5-ac6cf174bdb4"
    }
  ],
  "size": "1024x1024",
  "output_format": "png",
  "quality": "high",
  "usage": { "input_tokens": 32, "output_tokens": 4160, "total_tokens": 4192 }
}
```
**批量出图{Batch}::cURL**
```
curl --request POST \
  --url 'https://api.oairoute.com/v1/images/generations' \
  --header 'Authorization: Bearer YOUR_OAIRoute_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "gpt-image-2.5-flare",
  "prompt": "极简风格的科技公司 logo，单色，几何图形",
  "n": 4,
  "size": "1:1",
  "quality": "high"
}'
```
**批量出图{Batch}::Python**
```
import requests
url = "https://api.oairoute.com/v1/images/generations"
headers = {
    "Authorization": "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
}
payload = {
  "model": "gpt-image-2.5-flare",
  "prompt": "极简风格的科技公司 logo，单色，几何图形",
  "n": 4,
  "size": "1:1",
  "quality": "high"
}
res = requests.post(url, headers=headers, json=payload)
print(res.json())
```
**批量出图{Batch}::JavaScript**
```
const res = await fetch("https://api.oairoute.com/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_OAIRoute_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "model": "gpt-image-2.5-flare",
  "prompt": "极简风格的科技公司 logo，单色，几何图形",
  "n": 4,
  "size": "1:1",
  "quality": "high"
}),
});
console.log(await res.json());
```
**200 批量出图{Batch}**
```
{
  "created": 1763088302,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAAAQACAIAAADwf7zU…",
      "generation_id": "a3b37aae-9c63-46f1-acb5-ac6cf174bdb4"
    }
  ],
  "size": "1024x1024",
  "output_format": "png",
  "quality": "high",
  "usage": { "input_tokens": 32, "output_tokens": 4160, "total_tokens": 4192 }
}
```