# GPT Image 2

gpt-image-2、gpt-image-2-2K 和 gpt-image-2-4K 的同步与异步图片生成、参考图创作和接入限制。

## 推荐优先使用异步生成接口

<div style={{ color: "#dc2626", fontSize: "1.5rem", fontWeight: 800, lineHeight: 1.35 }}>
  gpt-image-2、gpt-image-2-2K 和 gpt-image-2-4K 都支持同步生成与异步生成；耗时较长时推荐使用异步接口。
</div>

> **三个模型都可以调用 `POST /v1/images/generations`。同步请求会在服务内部等待异步任务完成，客户端超时较短、批量并发或需要可靠轮询时，请改用 `POST /v1/images/generations/jobs`。**

图片生成和 URL 参考图创作推荐使用异步任务接口。异步任务能避免客户端长时间等待单个 HTTP 请求，也更适合并发提交、轮询和失败重试：

如果你使用 Codex、Claude Code 或 Cursor，不想手写请求和轮询代码，可以先打开 [Agent 生图 Skill 安装页](https://kaienapi.com/zh-CN/agent-image-generation)，复制对应命令后直接用自然语言生成并保存图片。

```http
POST /v1/images/generations/jobs
```

短耗时或兼容旧客户端时，也可以调用同步接口：

```http
POST /v1/images/generations
```

## 不推荐：图片 Edit 接口

<div style={{ color: "#dc2626", fontSize: "1.5rem", fontWeight: 800, lineHeight: 1.35 }}>
  图片 Edit 接口不推荐调用，请使用异步生成接口。
</div>

> **不推荐新接入调用 `POST /v1/images/edits`。需要参考图改图、换装、合成或多图创作时，请调用异步生成接口，并把图片 URL 放入 JSON `image` 数组。**

`/v1/images/edits` 仅保留给必须使用 OpenAI multipart Edit 语义的旧客户端：

```http
POST /v1/images/edits
```

## 异步文生图

创建任务：

```bash
curl https://kaienapi.com/v1/images/generations/jobs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "生成一张干净的耳机产品海报，白色背景，柔和光线",
    "size": "1024x1024",
    "quality": "low",
    "format": "jpeg"
  }'
```

响应会返回任务 ID 和初始状态：

```json
{
  "id": "imgtask_xxx",
  "status": "queued"
}
```

轮询结果：

```bash
curl https://kaienapi.com/v1/images/generations/jobs/imgtask_xxx \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

任务完成后状态为 `succeeded`，结果在 `data` 数组中；失败时状态为 `failed`，错误原因在 `error.message`。

## 轮询实现细节

图片任务的推荐接入方式是轮询。创建任务后，应用侧应把任务 ID 持久化，而不是只放在浏览器内存里。

建议保存这些字段：

| 字段 | 用途 |
|---|---|
| `id` | 后续查询任务状态 |
| `status` | 页面展示处理中、成功或失败 |
| `created_at` | 计算等待时间、排序和排查问题 |
| `model` | 展示任务来源，便于用户识别 |
| `prompt` 摘要 | 任务列表中展示用户输入 |
| `data` | 成功后的图片结果 |
| `error.message` | 失败时展示可读原因 |

推荐轮询节奏：

1. 创建任务后立即查询一次，确认任务已记录。
2. 前 30 秒每 `2-3` 秒查询一次。
3. 之后可放慢到每 `5-10` 秒一次。
4. 查询到 `succeeded` 或 `failed` 后停止轮询。
5. 页面关闭、刷新或用户稍后回来时，用已保存的任务 ID 继续查询。

不要在轮询超时后自动重新创建同一个任务。更稳的做法是保留任务 ID，把页面显示为“仍在处理中”，并允许用户手动刷新状态。

JavaScript 轮询示例：

```js
async function waitForImageJob(jobId, apiKey) {
  const terminal = new Set(["succeeded", "failed"]);
  const startedAt = Date.now();

  while (Date.now() - startedAt < 5 * 60 * 1000) {
    const response = await fetch(`https://kaienapi.com/v1/images/generations/jobs/${jobId}`, {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    });

    const job = await response.json();
    if (terminal.has(job.status)) {
      return job;
    }

    await new Promise((resolve) => setTimeout(resolve, 3000));
  }

  return { id: jobId, status: "running" };
}
```

结果读取逻辑要同时兼容 URL 和 base64：

```js
const image = job.data?.[0];
const src = image?.url || (image?.b64_json ? `data:image/png;base64,${image.b64_json}` : "");
```

## 异步参考图创作

远程图片应使用公网可访问的 OSS/CDN URL，并放入异步任务 JSON 的 `image` 数组。需要多张网络 URL 做参考图创作、换装、合成或改图时，推荐直接使用 `/v1/images/generations/jobs`。

```bash
curl https://kaienapi.com/v1/images/generations/jobs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "保留图 1 的人物特征，服饰参考图 2，鞋子参考图 3，生成白底全身 look 图。",
    "image": [
      "https://oss.example.com/model.jpg?x-oss-process=image/resize,w_1024/quality,q_85",
      "https://oss.example.com/outfit.jpg?x-oss-process=image/resize,w_1024/quality,q_85",
      "https://oss.example.com/shoes.jpg?x-oss-process=image/resize,w_1024/quality,q_85"
    ],
    "size": "960x1280",
    "quality": "standard",
    "format": "png"
  }'
```

### 参考图数量限制

- `gpt-image-2-2K`：最多 `8` 张参考图，传入 `9` 张或更多会返回“参考图过多”错误。
- `gpt-image-2-4K`：最多 `8` 张参考图，传入 `9` 张或更多会返回“参考图过多”错误。
- 标准版 `gpt-image-2` 的上限可能不同，不要在客户端把三个模型统一写死为 `8` 张；应根据所选模型处理接口返回。

参考图数量按 `image` 数组中的 URL 数量计算。建议在提交前显示已选数量，但最终限制仍以渠道返回为准。

## 同步兼容调用

如果客户端必须兼容 OpenAI Images 的同步返回格式，可以继续使用：

```http
POST /v1/images/generations
```

同步调用会一直等待结果返回。页面、移动端、Serverless、队列 worker 或批量并发场景不建议使用同步等待；这类场景请使用异步任务接口并保存任务 ID。

## 图片 URL 建议

- 图片地址必须公网可访问，且在请求期间不会过期。
- 大图建议先通过 OSS/CDN 图片处理 resize 到合适分辨率，例如长边 `1024`，再提交给模型。
- 多张参考图按语义顺序放入 `image` 数组，并在 prompt 中说明每张图的用途。

## 常用参数

| 参数 | 说明 |
|---|---|
| `model` | `gpt-image-2`、`gpt-image-2-2K` 或 `gpt-image-2-4K`；三个档位均支持同步和异步生成 |
| `prompt` | 描述生成目标、参考图用途、保留内容和改动范围 |
| `image` | 公网可访问的图片 URL 数组；2K、4K 模型最多 8 张 |
| `size` | 优先使用下方推荐尺寸，或传符合限制的自定义尺寸 |
| `quality` | `auto`、`low`、`medium`、`high` |
| `format` | `png`、`jpeg`、`webp` |

这里使用 `format`，不要写成 `output_format`。`gpt-image-2` 当前不支持 `n` 批量生成；一次请求只生成一张图片，需要多张结果时请发起多次请求。

## 推荐尺寸

这些预设尺寸通常出图更快，接入时建议优先使用：

| 尺寸 | 说明 |
|---|---|
| `auto` | 默认尺寸 |
| `1024x1024` | 方图 |
| `1536x1024` | 横图 |
| `1024x1536` | 竖图 |
| `2048x2048` | 2K 方图 |
| `2048x1152` | 2K 横图 |
| `2880x2880` | 最大方图 |
| `3840x2160` | 最大 16:9 横图 |
| `2160x3840` | 4K 竖图 |

## 尺寸限制

`gpt-image-2-2K` 与 `gpt-image-2-4K` 当前使用相同的尺寸边界。自定义尺寸时需要同时满足：

- `size` 使用 `WIDTHxHEIGHT` 格式，宽高均为正数。
- 最大边长不超过 `3840px`。
- 宽高都是 `16px` 的倍数。
- 长边与短边比例不超过 `3:1`。
- 总像素数不少于 `655,360`，且不超过 `8,294,400`。

常见边界：

| 画幅 | 最大合法尺寸 |
|---|---|
| 横图 | `3840x2160` |
| 竖图 | `2160x3840` |
| 方图 | `2880x2880` |

`3840x2176` 会因为总像素超限失败，`3856x2048` 会因为最长边超限失败，`1936x640` 会因为比例超过 `3:1` 失败，`1024x1025` 会因为不是 16 的倍数失败。

> **模型名决定模型档位和计费，`size` 决定实际输出尺寸。** 合法的大尺寸不会因为使用 `gpt-image-2-2K` 而自动缩回 2K；例如传入 `3840x2160` 时，实际输出可以是 `3840x2160`。

## 排查顺序

1. 先跑纯文生图，确认模型可用。
2. 再传一张 OSS/CDN 图片 URL。
3. 单图正常后测试多图数组。
4. 没有图片结果时，记录完整响应并确认图片字段位置。
5. 浏览器、移动端或后端调用超时时，应改为异步任务模式，不要让页面或请求线程长时间等待单个同步请求。