# 创建异步图片生成任务

`POST /v1/images/generations/jobs`

创建异步图片生成任务。**这是新接入图片生成和参考图改图的推荐接口。**接口会立即返回任务 ID，后台继续执行图片生成，客户端轮询查询结果，避免长时间同步等待。`gpt-image-2`、`gpt-image-2-2K` 和 `gpt-image-2-4K` 均支持本接口。

## 请求格式
使用 `application/json`。必须包含 `model` 和 `prompt`；如模型支持参考图，可选传 `image` URL 或 URL 数组。

## 推荐场景
- 页面、移动端或 Serverless 调用，不能长时间等待单个 HTTP 请求。
- 批量并发生成、多张图片生成或需要可靠重试。
- URL 参考图创作、换装、合成、改图等可能耗时较长的请求。

## 调用流程

1. `POST /v1/images/generations/jobs` 创建任务，保存返回的 `id`、创建时间、请求参数摘要和当前状态。
2. 创建后可以立即查询一次，确认任务已经记录。
3. 前 30 秒每 `2-3` 秒调用 `GET /v1/images/generations/jobs/{job_id}` 查询状态。
4. 之后可放慢到每 `5-10` 秒一次。
5. `status=succeeded` 时读取 `data` 数组；`status=failed` 时读取 `error.message`。
6. 页面刷新、浏览器关闭或用户稍后回来时，继续用保存的任务 ID 查询。

建议设置最长等待时间，例如 `3-5` 分钟。超过后不要自动重建任务，可以把页面显示为“仍在处理中”，稍后继续查询。临时网络错误可以等待下一轮重试。

## URL 参考图推荐
需要用 OSS/CDN 图片 URL 做参考图创作、换装、合成或改图时，推荐使用本接口。图片地址必须公网可访问，且在任务执行期间不会过期。

## 状态流转
创建后返回 `queued`，后台执行时变为 `running`，完成后为 `succeeded` 并返回 `data`，失败后为 `failed` 并返回 `error.message`。

Tags: 图片生成