# 图片生成

使用 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` 或 `images` 数组，可传 URL 或 Base64。**

> **`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-3.1-flash-image-preview` 和 `gemini-3-pro-image-preview` 也使用本页的图片生成接口。推荐通过 `/v1/images/generations/jobs` 创建任务，顶层传 `aspect_ratio`、`image_size` 和可选的参考图 `image` URL 数组；具体示例见 [Gemini 图像生成](/docs/images-video/gemini-image-preview)。
>
> `seedream-5.0` 走本页的 OpenAI Images 接口，但 `size` 填画面比例、`resolution` 选 `1k` 或 `2k`。见 [Seedream 5.0](/docs/images-video/seedream-5.0)。

## 文生图

```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 在请求期间不会过期。

### Base64 参考图

异步 JSON 请求支持直接传本地图片的 Base64，不需要先单独上传。服务会流式解码并上传到临时 COS 存储，再使用参考图 URL 调用渠道。

```json
{
  "model": "gpt-image-2",
  "prompt": "保留第一张图的主体，参考第二张图的背景和风格。",
  "images": [
    "data:image/jpeg;base64,<第一张图片的BASE64>",
    "data:image/png;base64,<第二张图片的BASE64>"
  ],
  "size": "1024x1024",
  "quality": "low",
  "response_format": "url"
}
```

这里的占位符必须替换为真实图片编码。单图只保留一个数组元素；`images` 也支持 `image_url` 对象数组。URL 和 Base64 可以混传，顺序保留，重复图片不合并。一次请求不要同时使用 `image`、`image[]` 和 `images`。

Base64 支持 PNG、JPEG、WebP、GIF，Data URL 前缀应与实际格式一致，也接受无前缀的标准 Base64。默认每张解码后最多 `10 MiB`，每次最多上传 `14` 张 Base64 图片、合计 `64 MiB`；模型和渠道可能有更小的参考图数量限制。

Base64 是输入参考图格式，不是输出格式；上面的 `response_format: "url"` 仍然返回图片 URL。多张参考图也不表示生成多张结果。完整的[单图、多图 curl 示例见 GPT Image 2 文档](/docs/images-video/gpt-image-2#base64-单图输入)。

## 结果读取

图片接口可能返回：

- 图片 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-3.1-flash-image-preview` 和 `gemini-3-pro-image-preview` 推荐使用 `POST /v1/images/generations/jobs`，保存任务 ID 后轮询结果；需要同步等待时使用 `POST /v1/images/generations`。这两个接口使用 `prompt`、顶层 `aspect_ratio` 和 `image_size`，成功后从 `data` 读取图片。参见 [Gemini 图像生成](/docs/images-video/gemini-image-preview)。