Skip to main content
本文档介绍本网关提供的 Sora 风格图片异步任务接口：创建任务后，通过轮询查询任务状态获取最终图片 URL。

​
适用范围

  • Gemini 图像模型：gemini-3-pro-image-preview、gemini-2.5-flash-image、gemini-2.5-flash-image-preview（含同系列分辨率 SKU）
  • Imagen 系列（仅文生图）：imagen-*
  • 异步接口返回的图片为 URL（24 小时有效），不返回 b64_json

​
前置条件：对象存储（必需）

异步图片任务强制要求配置对象存储（S3 或 AliOSS）用于：
  • 上传生成图片
  • 返回 24 小时有效的临时签名 URL
若对象存储未配置，调用异步接口会直接返回错误（error.code=storage_not_configured）。

​
接口列表

  • 创建文生图任务：POST /v1/images/generations/async
  • 创建改图任务：POST /v1/images/edits/async
  • 查询任务状态：GET /v1/images/generations/{id} / GET /v1/images/edits/{id}
任务 ID 统一为：
  • image_<ULID>（示例：image_01KCRVET35FAVZME1CEEED9VBS）

​
任务状态与轮询

查询接口返回的 status 可能为：
  • pending：排队中
  • in_progress：执行中
  • completed：已完成（可读取 data[].url）
  • failed：失败（返回 error.code / error.message）
建议轮询策略：
  • interval: 3–10 秒
  • timeout: 5–15 分钟（取决于服务负载情况与图片分辨率）

​
文生图：创建 + 轮询示例

​
1) 创建任务

curl -X POST "$BASE_URL/v1/images/generations/async" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "prompt": "A futuristic cityscape at sunset with flying cars",
    "n": 1,
    "size": "1024x1024",
    "response_format": "url"
  }'
响应示例： 
{
  "id": "image_01KCRVET35FAVZME1CEEED9VBS",
  "task_id": "image_01KCRVET35FAVZME1CEEED9VBS",
  "object": "image.generation",
  "created_at": 1700000000,
  "status": "pending",
  "progress": 0,
  "model": "gemini-3-pro-image-preview",
  "prompt": "A futuristic cityscape at sunset with flying cars"
}
task_id 为兼容字段，等同于 id。

​
2) 轮询查询结果

curl -X GET "$BASE_URL/v1/images/generations/image_01KCRVET35FAVZME1CEEED9VBS" \
  -H "Authorization: Bearer $TOKEN"
完成态响应示例： 
{
  "id": "image_01KCRVET35FAVZME1CEEED9VBS",
  "task_id": "image_01KCRVET35FAVZME1CEEED9VBS",
  "object": "image.generation",
  "created_at": 1700000000,
  "status": "completed",
  "progress": 100,
  "completed_at": 1700000066,
  "expires_at": 1700086466,
  "model": "gemini-3-pro-image-preview",
  "data": [
    { "url": "https://example.com/signed-url.png" }
  ]
}
失败态响应示例： 
{
  "id": "image_01KCRVET35FAVZME1CEEED9VBS",
  "task_id": "image_01KCRVET35FAVZME1CEEED9VBS",
  "object": "image.generation",
  "created_at": 1700000000,
  "status": "failed",
  "progress": 0,
  "error": {
    "code": "task_failed",
    "message": "任务执行失败，请稍后重试"
  }
}

​
改图：创建 + 轮询示例

改图异步任务仅支持 Gemini 图像模型（gemini-*-image*），Imagen 暂不支持编辑。
创建改图任务使用 multipart/form-data： 
curl -X POST "$BASE_URL/v1/images/edits/async" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=将这张图片转换为油画风格" \
  -F "response_format=url" \
  -F "image=@/path/to/image.png"
也可通过 image_urls[] 传入图片 URL： 
curl -X POST "$BASE_URL/v1/images/edits/async" \
  -H "Authorization: Bearer $TOKEN" \
  -F "model=gemini-3-pro-image-preview" \
  -F "prompt=将这张图转换为油画风格（URL 参考图）" \
  -F "response_format=url" \
  -F "image_urls[]=https://example.com/base.png" \
  -F "image_urls[]=https://example.com/style-ref.png"
轮询接口： 
curl -X GET "$BASE_URL/v1/images/edits/{id}" \
  -H "Authorization: Bearer $TOKEN"

​
与同步接口的关系

  • 同步接口：POST /v1/images/generations、POST /v1/images/edits
    • 可选择 response_format=b64_json 或 response_format=url
    • 若要求 url 但上游只返回 base64，则需要配置 storage 才能上传并生成 URL
  • 异步接口：POST /v1/images/*/async
    • response_format 固定为 url（传入 b64_json 会被忽略）
    • 强制要求对象存储（S3/AliOSS），返回 24h 临时 URL
若你只需要 OpenAI 风格同步调用，请参考《图像生成 (OpenAI 风格)》。