异步图片生成接口文档

本文档说明异步图片生成接口：

POST /v1/images/async/generations：提交异步图片生成任务

GET /v1/images/async/generations/{task_id}：查询任务状态与结果

基础信息

Base URL：你的网关地址（例如 https://api.example.com）

认证方式：Authorization: Bearer sk-xxxx

请求/响应格式：application/json

依赖：服务端必须启用 Redis（否则接口返回 503）

通用请求头：

1) 提交任务

方法：POST

路径：/v1/images/async/generations

请求参数（Body）

字段	类型	必填	说明
`model`	string	是	模型名。该接口不会自动补默认模型，需显式传入可用模型。
`prompt`	string	是	图片生成提示词，不能为空。
`n`	integer	否	生成图片数量，默认 `1`。
`size`	string	否	尺寸（如 `1024x1024`、`1792x1024`、`1024x1792`），默认按 `1:1` 处理。
`quality`	string	否	质量参数（如 `hd`、`high`、`2K` 等）。

说明：

当前异步链路实际使用字段为：model、prompt、n、size、quality。

其他兼容字段（如 response_format、style、background、watermark 等）即使传入，当前异步实现也不会参与上游请求构造。

请求示例

成功响应（200）

{
  "task_id": "task_3f2ab8c2c5f643fbbaf7878df740a6f4",
  "status": "SUBMITTED",
  "model": "imagen-4.0-generate-001",
  "created_at": 1773728401
}

返回字段说明

字段	类型	说明
`task_id`	string	任务 ID，格式为 `task_` + 32位随机串。
`status`	string	初始状态固定为 `SUBMITTED`。
`model`	string	请求时传入的模型名。
`created_at`	integer	任务创建时间（Unix 秒级时间戳）。

2) 查询任务

方法：GET

路径：/v1/images/async/generations/{task_id}

路径参数

参数	类型	必填	说明
`task_id`	string	是	提交任务时返回的任务 ID。

请求示例

响应字段（通用）

字段	类型	说明
`task_id`	string	任务 ID。
`status`	string	任务状态：`SUBMITTED` / `IN_PROGRESS` / `SUCCESS` / `FAILURE`。
`model`	string	提交时模型名。
`progress`	string	进度百分比字符串（如 `0%`、`30%`、`70%`、`100%`）。
`created_at`	integer	任务创建时间（Unix 秒级时间戳）。

成功完成示例（`status=SUCCESS`）

{
  "task_id": "task_3f2ab8c2c5f643fbbaf7878df740a6f4",
  "status": "SUCCESS",
  "model": "imagen-4.0-generate-001",
  "progress": "100%",
  "created_at": 1773728401,
  "created": 1773728416,
  "data": [
    {
      "url": "https://cdn.example.com/xxx.png",
      "b64_json": "",
      "revised_prompt": ""
    }
  ]
}

data 内单项字段说明：

字段	类型	说明
`url`	string	图片 URL（若服务端配置了对象存储，通常返回此字段）。
`b64_json`	string	图片 base64（未上传或上传失败时可能返回）。
`revised_prompt`	string	上游返回的修订提示词（如有）。

失败示例（`status=FAILURE`）

{
  "task_id": "task_3f2ab8c2c5f643fbbaf7878df740a6f4",
  "status": "FAILURE",
  "model": "imagen-4.0-generate-001",
  "progress": "100%",
  "created_at": 1773728401,
  "fail_reason": "上游错误: prompt blocked"
}

状态流转

典型状态流转：

SUBMITTED -> IN_PROGRESS -> SUCCESS / FAILURE

常见进度值（实现细节，可能随版本调整）：

0%：刚提交

10%：Worker 开始处理

30%：已完成上游请求提交

50%：长任务轮询中（Imagen 路径）

70%：已拿到上游响应并解析中（Gemini Native 路径）

100%：完成或失败

错误响应

统一错误结构

多数错误返回：

{
  "error": {
    "message": "错误信息",
    "type": "错误类型",
    "code": "可选错误码"
  }
}

常见错误场景

HTTP 状态码	`error.type`	场景
`400`	`invalid_request_error` / `new_api_error`	参数非法，例如 `prompt` 为空、请求体格式错误、缺少 `model`。
`401`	`new_api_error`	未提供或无效 `Authorization`。
`403`	`new_api_error`	用户/令牌无权限或被封禁。
`404`	`not_found`	查询不存在的 `task_id`。
`500`	`internal_error`	服务内部错误（保存任务失败、入队失败、读取任务失败等）。
`503`	`service_unavailable` / `new_api_error`	Redis 未启用，或无可用渠道。

轮询建议

建议每 2~5 秒轮询一次查询接口。

任务数据默认保留约 24 小时（Redis TTL），建议业务侧及时拉取并持久化结果。

任务失败会自动执行退费（若该请求发生了预扣费）。

README

异步图片生成接口文档#

基础信息#

1) 提交任务#

请求参数（Body）#

请求示例#

成功响应（200）#

返回字段说明#

2) 查询任务#

路径参数#

请求示例#

响应字段（通用）#

成功完成示例（status=SUCCESS）#

失败示例（status=FAILURE）#

状态流转#

错误响应#

统一错误结构#

常见错误场景#

轮询建议#

异步图片生成接口文档

基础信息

1) 提交任务

请求参数（Body）

请求示例

成功响应（200）

返回字段说明

2) 查询任务

路径参数

请求示例

响应字段（通用）

成功完成示例（`status=SUCCESS`）

失败示例（`status=FAILURE`）

状态流转

错误响应

统一错误结构

常见错误场景

轮询建议