异步图片生成与编辑接入指南

异步图片接口适用于生成或编辑耗时较长、客户端不希望保持长连接的场景。接口使用平台现有 API Key，成功结果保持 OpenAI Images 响应结构。

1. 接口

用途	方法	路径
创建图片生成任务	POST	/v1/images/generations/tasks
创建图片编辑任务	POST	/v1/images/edits/tasks
查询轻量状态	GET	/v1/images/tasks/{task_id}/status
查询任务结果	GET	/v1/images/tasks/{task_id}

Idempotency-Key 为可选请求头，建议在需要安全重试时携带。同一身份范围、同一操作、相同幂等键和相同请求会返回同一个任务；同一幂等键对应不同请求时返回 409。未携带时每次提交都创建新任务；若提交响应超时后直接重试，可能生成多个任务。

2. 创建图片编辑任务

编辑接口使用 multipart/form-data，参数与 OpenAI 兼容图片编辑接口一致。image 必填，mask 可选且必须为 PNG，并与第一张图片尺寸一致。

curl "$BASE_URL/v1/images/edits/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: edit-order-20260907-001" \
  -F "model=gpt-image-2" \
  -F "prompt=将背景改为纯白色，保留主体" \
  -F "image=@source.png;type=image/png" \
  -F "mask=@mask.png;type=image/png" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "quality=low" \
  -F "output_format=png"

多图编辑可重复提交 image，也可使用 image[] 或连续的 image[0]、image[1]。一次请求只能选择其中一种形式，图片顺序会被保留。

受理成功返回 HTTP 202。响应头包含 Location（结果查询地址）和 Retry-After: 3，响应正文示例：

{
  "id": "img_task_...",
  "object": "image.edit.task",
  "operation": "edit",
  "model": "gpt-image-2",
  "status": "queued",
  "result_status": "not_ready",
  "status_url": "/v1/images/tasks/img_task_.../status",
  "response_url": "/v1/images/tasks/img_task_...",
  "created_at": 1788768000,
  "expires_at": 1791360000
}

3. 创建图片生成任务

curl "$BASE_URL/v1/images/generations/tasks" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: generation-order-20260907-001" \
  -d '{"model":"gpt-image-2","prompt":"一只白色杯子，纯色背景","n":1,"size":"1024x1024","quality":"low"}'

生成任务的 object 为 image.generation.task，operation 为 generation。

受理成功返回 HTTP 202，响应正文示例：

{
  "id": "img_task_1788768000_example",
  "object": "image.generation.task",
  "operation": "generation",
  "model": "gpt-image-2",
  "status": "queued",
  "result_status": "not_ready",
  "status_url": "/v1/images/tasks/img_task_1788768000_example/status",
  "response_url": "/v1/images/tasks/img_task_1788768000_example",
  "created_at": 1788768000,
  "expires_at": 1791360000
}

4. 查询状态和结果

推荐先轮询轻量状态接口。处理中状态包括 accepting、queued、in_progress 和 output_pending。

curl "$BASE_URL/v1/images/tasks/$TASK_ID/status" \
  -H "Authorization: Bearer $API_KEY"

任务处理中时，状态接口返回 HTTP 200。响应头包含 Retry-After: 3，响应正文示例：

{
  "id": "img_task_1788768000_example",
  "object": "image.generation.task.status",
  "operation": "generation",
  "model": "gpt-image-2",
  "status": "in_progress",
  "result_status": "not_ready",
  "status_url": "/v1/images/tasks/img_task_1788768000_example/status",
  "response_url": "/v1/images/tasks/img_task_1788768000_example",
  "created_at": 1788768000,
  "started_at": 1788768002,
  "expires_at": 1791360000
}

任务成功后，状态接口仍返回 HTTP 200，示例：

{
  "id": "img_task_1788768000_example",
  "object": "image.generation.task.status",
  "operation": "generation",
  "model": "gpt-image-2",
  "status": "succeeded",
  "result_status": "ready",
  "status_url": "/v1/images/tasks/img_task_1788768000_example/status",
  "response_url": "/v1/images/tasks/img_task_1788768000_example",
  "created_at": 1788768000,
  "started_at": 1788768002,
  "finished_at": 1788768020,
  "expires_at": 1791360000,
  "result_expires_at": 1789372820
}

图片编辑任务使用相同字段，但 object 为 image.edit.task.status，operation 为 edit。

状态为 succeeded 且 result_status 为 ready 后，读取结果：

curl "$BASE_URL/v1/images/tasks/$TASK_ID" \
  -H "Authorization: Bearer $API_KEY"

任务仍在处理时，结果接口返回 HTTP 202，响应头包含 Retry-After: 3，正文为当前任务对象，例如：

{
  "id": "img_task_1788768000_example",
  "object": "image.generation.task",
  "operation": "generation",
  "model": "gpt-image-2",
  "status": "in_progress",
  "result_status": "not_ready",
  "status_url": "/v1/images/tasks/img_task_1788768000_example/status",
  "response_url": "/v1/images/tasks/img_task_1788768000_example",
  "created_at": 1788768000,
  "started_at": 1788768002,
  "expires_at": 1791360000
}

结果成功时返回 HTTP 200，正文与对应的 OpenAI 图片生成或编辑成功响应一致，例如：

{
  "created": 1788768020,
  "data": [
    {"url": "https://..."}
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 100,
    "total_tokens": 112
  }
}

以上时间字段均为 Unix 秒级时间戳。started_at、finished_at 和 result_expires_at 仅在已有对应时间时返回；result_expires_at 只表示结果查询接口中响应数据的可读取期限，不代表 data[].url 指向图片的存储期限。客户端应遵循 Retry-After 响应头，避免高频轮询。

5. 权限范围

同一用户可以使用自己的其他有效 API Key 查询个人任务。企业任务只能由同一企业授权范围内的有效凭证查询；项目任务还受项目访问权限约束。跨用户、个人与企业之间、不同企业之间的查询均返回与任务不存在相同的响应。

6. 常见错误

HTTP 状态	错误码	含义
400	invalid_idempotency_key	携带的幂等键格式不合法
400	invalid_image_edit_request	编辑表单、图片、蒙版或文件限制不合法
400	unsupported_parameter	使用了异步接口不支持的流式参数
409	idempotency_conflict	同一幂等键被用于不同请求
413	request_too_large	请求正文超过当前异步图片接口上限
429	image_async_accept_busy	当前请求解析容量繁忙，请按 Retry-After 稍后重试
429	image_async_queue_full	当前未完成任务过多，请稍后重试

错误响应正文统一使用以下结构，例如：

{
  "error": {
    "message": "The image edit request is invalid",
    "type": "image_async_error",
    "param": "",
    "code": "invalid_image_edit_request"
  }
}

API Key、幂等键和上传图片不应写入公开日志。任务 ID 可用于业务侧关联，但不能替代 API Key 鉴权。