# 图片生成

使用 OpenAI 兼容图片接口生成图片、编辑图片和读取图片结果。

## 重要：优先使用异步生成接口

<div style={{ color: "#dc2626", fontSize: "1.5rem", fontWeight: 800, lineHeight: 1.35 }}>
  图片 Edit 接口不推荐调用。GPT Image 2 的 1K、2K、4K 档位均支持同步和异步生成，耗时较长时优先使用异步接口。
</div>

> **新接入统一推荐 `POST /v1/images/generations/jobs`。`POST /v1/images/edits` 不推荐调用。参考图改图也请使用异步生成接口的 JSON `image` 数组。**

> **`gpt-image-2`、`gpt-image-2-2K` 和 `gpt-image-2-4K` 都可以调用 `/v1/images/generations`；同步请求会在服务内部等待异步任务完成。批量并发或客户端超时较短时，请使用 `/v1/images/generations/jobs`。**

图片生成优先使用异步任务：

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

创建任务后保存任务 ID，再轮询查询结果。页面、移动端、Serverless、批量并发和参考图改图场景都建议使用这种方式，避免客户端长时间等待单个同步请求。

同步兼容调用使用：

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

URL 参考图创作、换装、合成或改图，推荐使用异步任务 JSON 接口，把公网图片 URL 放到 `image` 数组。

multipart 图片 Edit 接口仅用于兼容旧客户端，不推荐新接入：

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

> Gemini 图像模型不走这里的图片接口。它们使用聊天接口返回图片，宽高比放在 `extra_body.google.image_config.aspect_ratio`；不同模型对 16:9 的支持不完全一致。见 [Gemini 图像生成](/docs/images-video/gemini-image-preview)。

## 文生图

```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",
    "n": 1
  }'
```

## 参考图创作

如果使用远程图片 URL，优先把 OSS 或 CDN 图片 URL 放到异步任务 JSON 的 `image` 数组里。多张网络 URL 做参考图创作、换装、合成或改图时，推荐使用 `/v1/images/generations/jobs` 创建任务并轮询结果。

```json
{
  "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",
  "n": 1
}
```

大图建议先通过 OSS/CDN 图片处理 resize 到合适分辨率，例如长边 `1024`，并确保 URL 在请求期间不会过期。

## 结果读取

图片接口可能返回：

- 图片 URL。
- `b64_json`。
- 异步任务 ID。

接入时不要只写死一个字段路径。需要长期访问的结果应保存到自己的对象存储。

## 推荐轮询流程

图片生成、参考图创作和改图任务首推“创建任务 + 轮询结果”。不要让页面、移动端或 Serverless 函数一直等待同步图片请求返回。

1. 调用 `POST /v1/images/generations/jobs` 创建任务。
2. 保存返回的 `id`、创建时间、请求参数摘要和当前状态。
3. 每隔 `2-3` 秒调用 `GET /v1/images/generations/jobs/{job_id}` 查询一次。
4. 查询到 `queued` 或 `running` 时继续等待，并在页面展示处理中状态。
5. 查询到 `succeeded` 时读取 `data` 数组，展示图片，并把需要长期访问的图片保存到对象存储。
6. 查询到 `failed` 时读取 `error.message`，把任务标记为失败，并允许用户修改 prompt 或参考图后重新提交。

轮询建议设置最长等待时间，例如 `3-5` 分钟。超过后不要丢弃任务 ID，可以把页面状态显示为“仍在处理中”，稍后继续用同一个任务 ID 查询。用户刷新页面或稍后回来时，也应从你保存的任务 ID 恢复进度。

```bash
JOB_ID="imgtask_xxx"

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

返回示例：

```json
{
  "id": "imgtask_xxx",
  "status": "succeeded",
  "data": [
    {
      "url": "https://example.com/result.png"
    }
  ]
}
```

前端或后端轮询时只在终态停止：`succeeded`、`failed`。如果网络请求临时失败，可以等待下一轮继续查询；不要立刻重复创建新任务，避免同一张图被重复生成。

## 选错接口时的表现

如果把 Gemini 图像模型提交到 `/v1/images/generations`，请求可能返回“不支持图片生成接口”的错误。这个错误通常不是宽高比参数失效，而是接口选错了。

这类模型请改用：

```http
POST /v1/chat/completions
```