# GPT Image 2.6 Flare — /images/generations

GPT Image 2.6 Flare 生图接口：OpenAI 2026 年 11 月发布的图片模型中出图干净、平滑的风格分支，适合封面、海报和要清晰文字的版面。异步任务，用法和 GPT Image 2.5 相同；1K / 2K / 4K 三档、15 种比例，交付生成的原图，按张计费，失败不收费。也能出 1K 的 GIF 动图（Beta）和 1K 的 SVG 矢量图。要 `xhigh` / `max` 画质请用按 token 计费的 `gpt-image-2.6-flare-token`。

**端点:** `POST https://kovapi.com/v1/images/generations`

## 快速开始

三步跑通：提交任务 → 查询结果 → 拿到图片链接。把 YOUR_API_KEY 换成你的 Key，下面的命令可以直接运行。

**第 1 步 · 提交任务（立刻返回任务号，HTTP 202）**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare", "prompt": "极简风格的产品图：浅色背景上的一只白色陶瓷杯，柔和的侧光", "size": "16:9", "resolution": "2K"}'
```

返回（HTTP 202）

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gpt-image-2.6-flare"
}
```

**第 2 步 · 每 2–3 秒查询一次，直到 `status` 变成 `succeeded` 或 `failed`**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

成功时的返回

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gpt-image-2.6-flare",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.6-flare"}
}
```

**第 3 步 · `data[0].url` 就是图片链接（PNG），保留 7 天；需要长期使用，请下载到你自己的存储。**

**完整示例（Python：提交 → 等待 → 保存到本地）**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. 提交任务
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2.6-flare",
    "prompt": "极简风格的产品图：浅色背景上的一只白色陶瓷杯，柔和的侧光",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. 每 3 秒查询一次，直到结束
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. 下载图片
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gpt-image-2.6-flare.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## 认证
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## 请求参数

`POST /v1/images/generations` 的请求体（JSON）：

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| model | string | 是 | 模型 id：`gpt-image-2.6-flare`。 |
| prompt | string | 是 | 画面描述。图生图时写清楚要怎么改。 |
| size | string | 否 | 比例，表中 15 种之一，例如 `16:9`；也可以写像素尺寸，或写 `auto`（带参考图时跟随第一张参考图的比例）。不传时出 1:1。 |
| resolution | string | 否 | 档位：`1K`（默认）、`2K`、`4K`。 |
| quality | string | 否 | 画质：`low`、`medium`（默认）或 `high`，1K / 2K / 4K 都生效，价格不变；`auto` 按 medium 处理。`xhigh` 和 `max` 只在按 token 计费的 `gpt-image-2.6-flare-token` 上提供，这里传了会在提交时返回 400，不扣费。 |
| image / images | string / array | 否 | 参考图，传了就是图生图：`image` 传一张，`images` 传多张（最多 16 张）。可以是公网图片链接、data: URI 或 base64。 |
| n | integer | 否 | 张数。建议不传：要多张图请同时提交多个任务。传了 `n` 时按 n 张预扣，按实际交付的张数结算。 |
| callback_url | string | 否 | 任务结束时把结果推送到这个地址，见下文的 Webhook。 |
| complexity | string | 否 | 构思程度：`low`、`medium` 或 `high`，不传时用模型的默认值。越高越适合密集文字、复杂版面和多个物体的关系，出图更慢，也可能改动你不想改的地方；只改局部（换背景、改招牌）时用 `low`。不影响价格。 |
| moderation | string | 否 | 审核强度：`auto`（默认）或 `low`（放宽一些，仍然遵守 OpenAI 的内容政策）。 |
| output_compression | integer | 否 | 压缩程度，0–100 的整数，只用于 `jpeg` / `webp` 输出，数值越小文件越小。 |
| mask_url | string | 否 | 局部重绘的蒙版：一张和第一张参考图尺寸相同的 PNG，透明的部分是要改的区域。需要参考图；不能和 `markup_url` 同时用。模型会参考蒙版，但不保证严格只改透明区域。 |
| markup_url | string | 否 | 标注层：一张透明 PNG，在要改的位置画圈或标记，叠在第一张参考图上，再在提示词里说怎么改，例如「把红圈里的花瓶改成蓝色，并去掉红圈」。需要参考图；不能和 `mask_url` 同时用；最多 1677 万像素。 |
| frame_count | integer | 否 | GIF 的帧数，2–12，默认 9。只在 `output_format` 为 `gif` 时使用。 |
| frame_duration_ms | integer | 否 | GIF 每帧显示的毫秒数，20–2000，默认 200（按 10 毫秒取整）。只在 `output_format` 为 `gif` 时使用。 |

`background` 可以写 `transparent`（透明背景，请配 PNG 或 WebP 输出）；`output_format` 可选 `png`（默认）、`jpeg`、`webp`、`gif`（见下方「GIF 动图」）、`svg`（见下方「SVG 矢量图」），交付的文件就是这个格式。`n` 只能是 1，要多张请同时提交多个任务。表里没有的参数会在提交时返回 400 `unsupported_image_parameter`，不扣费；结果通过 `url` 返回。

## 价格

按张计费，价格只看档位，跟比例、文生图还是图生图无关。提交时按档位预扣，任务失败全额退回。1 积分 = $0.005。

| 档位 | 积分 / 张 | 美元 / 张 |
| --- | --- | --- |
| 1K | 3 | $0.015 |
| 2K | 6 | $0.03 |
| 4K | 10 | $0.05 |

## 比例、分辨率与输出尺寸

`size` 写比例，`resolution` 写档位。交付生成的原图，不裁切、不缩放，尺寸见下表：宽高都是 16 的倍数，4K 单边不超过 3840、总像素约 830 万以内。

| 比例 | 1K | 2K | 4K |
| --- | --- | --- | --- |
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:4 | 768x1024 | 1536x2048 | 2480x3312 |
| 4:3 | 1024x768 | 2048x1536 | 3312x2480 |
| 2:3 | 672x1024 | 1360x2048 | 2336x3520 |
| 3:2 | 1024x672 | 2048x1360 | 3520x2336 |
| 9:16 | 608x1088 | 1152x2048 | 2160x3840 |
| 16:9 | 1088x608 | 2048x1152 | 3840x2160 |
| 4:5 | 816x1024 | 1632x2048 | 2576x3216 |
| 5:4 | 1024x816 | 2048x1632 | 3216x2576 |
| 1:2 | 576x1152 | 1024x2048 | 1920x3840 |
| 2:1 | 1152x576 | 2048x1024 | 3840x1920 |
| 9:21 | 544x1264 | 880x2048 | 1648x3840 |
| 21:9 | 1264x544 | 2048x880 | 3840x1648 |
| 1:3 | 480x1440 | 672x2016 | 1280x3840 |
| 3:1 | 1440x480 | 2016x672 | 3840x1280 |

- 支持表中 15 种比例，其他比例在提交时返回 400，不扣费。`size` 写 `auto` 并带参考图时，按第一张参考图最接近的比例出图；不带参考图时出 1:1。1K 的几种窄长比例低于模型的最小像素，按表中放大后的尺寸出图（如 16:9 出 1088×608）。

- `size` 也可以写像素尺寸（如 `1536x1024`），比例要是表中 15 种之一：宽高向下取到 16 的倍数，超出该档上限时等比缩小，太小时等比放大到模型的最小像素（约 65.5 万）。档位按 `resolution` 定；没写 `resolution` 时看长边：不超过 1536 为 1K，不超过 2048 为 2K，更大为 4K。长边范围：1K 为 512–1536，2K 为 2016–2304，4K 为 2049–4096，超出时提交即返回 400，不扣费。

## 画质与原生分辨率

- 不传 `quality` 时按 **medium** 出图。`low`、`medium`、`high` 在 1K / 2K / 4K 都生效，文生图和图生图一样，价格只看分辨率档；`auto` 按 medium 处理。要 `xhigh` 或 `max`，请用按 token 计费的 `-token` 版本。

- `quality` 写成 `1K`、`2K` 或 `4K`、又没传 `resolution` 时，按分辨率档处理（出图尺寸和价格都按这一档）。

- 原生出图的档位始终原生出图：忙时任务排队等候，实在出不了图就失败并全额退款，不会拿 1K 图放大来交差。

## GIF 动图（Beta）

`output_format` 写 `gif` 就出循环播放的 GIF 动图，每个 10 积分（$0.05），失败不收费。只有 1K，只能用提示词生成（暂不支持参考图），不支持透明背景、蒙版、标注层和压缩。`frame_count` 设帧数（2–12，默认 9），`frame_duration_ms` 设每帧时长（20–2000 毫秒，默认 200）。所有帧画在一张图上再拆开，所以帧越多每帧越小：`size` 写比例时按下表取放得下的最大尺寸；写像素尺寸时必须放得下，否则提交时返回 400，不扣费。在提示词里写清楚动作和怎么循环，效果更好。

| 比例 | 帧数 2–8 | 帧数 9 | 帧数 10–12 |
| --- | --- | --- | --- |
| 1:1 | 960x960 | 960x960 | 816x816 |
| 3:4 | 880x1168 | 832x1104 | 720x960 |
| 4:3 | 1168x880 | 1104x832 | 960x720 |
| 2:3 | 816x1216 | 768x1152 | 672x1008 |
| 3:2 | 1232x816 | 1168x784 | 1008x672 |
| 9:16 | 752x1344 | 720x1280 | 624x1104 |
| 16:9 | 1344x752 | 1280x720 | 1104x624 |
| 4:5 | 912x1136 | 848x1056 | 736x928 |
| 5:4 | 1136x912 | 1056x848 | 928x736 |
| 1:2 | 720x1440 | 640x1280 | 576x1152 |
| 2:1 | 1440x720 | 1280x640 | 1152x576 |
| 9:21 | 656x1536 | 544x1264 | 544x1264 |
| 21:9 | 1536x656 | 1280x544 | 1264x544 |
| 1:3 | 576x1728 | — | — |
| 3:1 | 1728x576 | — | — |

表中「—」表示这个比例出不了这么多帧。GIF 的签名和静图一样是 OpenAI 的 C2PA 凭证，交付的是生成的原文件。

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare", "prompt": "A cat on a windowsill slowly blinking, soft morning light, seamless loop.", "size": "1:1", "output_format": "gif", "frame_count": 9, "frame_duration_ms": 120}'
```

## SVG 矢量图

`output_format` 写 `svg` 就得到一个 SVG 矢量文件：可以无损放大，也能在设计软件里继续编辑，适合图标、Logo、插画和简单的信息图。每个 10 积分（$0.05），失败不收费。按张计费的版本只有 1K、每次 1 个；可以只用提示词，也可以带参考图（比如把一张图重画成矢量风格）。不支持透明背景、蒙版和标注层。交付的是不含脚本、外部链接和内嵌位图的静态 SVG，画布尺寸和你要的尺寸一致；SVG 是文本文件，不带 C2PA 签名。要 2K / 4K 画布，请用按 token 计费的 `gpt-image-2.6-flare-token`。

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare", "prompt": "A minimalist flat logo for a bakery: a wheat stalk inside a circle, two colours, clean lines.", "size": "1:1", "output_format": "svg"}'
```

## 图生图与参考图

- 传 `image`（一张）或 `images`（多张，最多 16 张，多出的不用）就是图生图，在提示词里写清楚要怎么改。也可以调用 `POST /v1/images/edits`，参数相同。

- 两个接口都只收 JSON 请求体，不支持 multipart 上传文件，所以 OpenAI SDK 的 `images.edit()` 不能直接用，请按下面的示例传链接或 base64。

- 每张参考图可以是公网图片链接（http / https）、data: URI 或纯 base64，单张不超过 16MB，格式限 PNG、JPEG 或 WebP；其他格式的参考图会让任务失败并全额退款。

- 链接要能直接下载到图片本身，不能是网页、需要登录或有防盗链的地址。读不到的参考图会在提交时直接返回 400，写明是哪一张、什么原因，不建任务、不扣费。

- 输出比例由 `size` 决定，不跟随参考图；想保持原图比例，就把 `size` 设成和原图一样的比例。

- 参考图由我们代为托管，保留 7 天。

**两张参考图的图生图**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare", "prompt": "保留画面里的人物，把背景换成夜晚的海边，加上暖色的灯串", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## 任务状态与返回字段

`GET /v1/images/jobs/{id}` 返回的状态如下，每个字段的说明见 [异步任务](https://docs.kovapi.com/zh/guide/async-jobs#fields)。建议每 2–3 秒查一次，或者用 Webhook。

| 状态 | 含义 |
| --- | --- |
| queued | 排队中。返回里带 `queue_position`（前面还有几个任务）和 `eta_seconds`（预计等待秒数）。 |
| processing | 生成中。 |
| succeeded | 已完成。结果在 `data[0].url`，计费明细在 `usage`。 |
| failed | 失败。原因在 `error`，预扣的积分已全额退回。 |

同一个账号最多 50 个任务同时生成，更多的任务按提交顺序排队；排队超过 15 分钟还没开始的任务会自动失败并全额退款。任务记录保留 3 天，图片链接保留 7 天。

## 出图时间

从提交到拿到结果通常 20–60 秒；4K、多张参考图的改图和忙时排队会更久，个别任务要一两分钟。

近 7 天真实调用：中位 26 秒，90% 在 70 秒 内完成。

## 错误与退款

提交时出错会直接返回 HTTP 4xx / 5xx，不建任务、不扣费；提交成功后的失败写在查询结果里，预扣的积分全额退回。全部错误码见 [错误码](https://docs.kovapi.com/zh/guide/errors)。

### 提交时返回的错误

| HTTP | code | 原因 | 怎么办 |
| --- | --- | --- | --- |
| 400 | missing_prompt | `/v1/images/generations` 没有 `prompt`。 | 补上 `prompt`。 |
| 400 | invalid_request | 参考图读不到（链接打不开、不是图片、超过 16MB 等，`message` 写明是第几张、什么原因），`/v1/images/edits` 没带参考图，或请求体不是 JSON 对象、`n` 不是整数。 | 按 `message` 修改后重新提交。 |
| 400 | model_not_found | 型号写错、没有传 `model`，或这个型号不能用在这个接口上（例如拿对话模型调生图接口）。 | 以 `GET /v1/models` 或 [API 手册](https://docs.kovapi.com/zh/api) 里的模型 id 为准。 |
| 401 | invalid_api_key | Key 不存在、已删除或已停用，或者账号已停用。 | 到控制台「API Keys」页面检查这把 Key。 |
| 402 | insufficient_quota | 余额不够预扣这一单。网关先按这一单可能的最高费用预扣，同时发很多请求时也可能出现。 | 如果是并发突发，稍等几秒重试；否则充值。 |
| 429 | rate_limit_exceeded | 超过了这把 Key 设置的每分钟请求数（按最近 60 秒计）。不带 `Retry-After`。 | 等几秒再试，或在控制台调高这把 Key 的上限。 |
| 503 | model_maintenance | 型号维护中，暂停接单，期间不会改由其他模型作答。 | 维护结束后重试，进度见 [服务状态](https://kovapi.com/zh/status)。 |
| 503 | service_unavailable | 我们这边临时出错，例如保存参考素材失败；`/v1/responses` 暂时无法处理时也返回 503，并带 `Retry-After`。 | 稍后重试。 |

### 任务失败（`status` 为 `failed`）

| code | 什么时候出现 | 怎么办 |
| --- | --- | --- |
| moderation_blocked | 图片：模型方的安全审核拒绝了提示词或参考图（也可能是 `content_policy_violation`）。 | 改写提示词或更换参考图；原样重交通常还会被拒。 |
| upstream_error | 其他失败：自动重试后仍然失败、排队 15 分钟还没开始、上游拒绝但没有说明原因等，`message` 写明具体情况。 | 通常重新提交就能成功。 |

## 用 Webhook 代替轮询

提交时加上 `callback_url`，任务一结束（成功或失败），网关就把和查询接口完全一样的结果推送到这个地址，带签名，失败会自动重试。也可以在控制台「设置 → Webhook」里配一个账户级地址。 [Webhook 文档 →](https://docs.kovapi.com/zh/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare", "prompt": "极简风格的产品图：浅色背景上的一只白色陶瓷杯，柔和的侧光", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```
