异步图像任务

适用场景

这套接口适合耗时较长的图像生成链路。调用方先提交任务，再轮询结果，不需要一直阻塞等待首个请求返回。

整体流程

POST /v1beta/models/{model}:generateContent 提交任务要求最终解析出的 output 为 url，可放在 query 或请求体
从 202 Accepted 响应中拿到 id
单任务可用 GET /v1/tasks/{id} 轮询状态
多任务可用 POST /v1/tasks/batch-get 批量查询状态
任务成功后读取返回体里的图片 URL
或直接访问 GET /v1/tasks/{id}/content

1. 提交任务

Base URL

text

https://async.xinbao-ai.com

端点

text

POST /v1beta/models/{model}:generateContent

鉴权

http

Authorization: Bearer <API_KEY>

关键约束

最终输出必须解析为 url
output=url 不强制写在请求地址上，写在请求体里也可以
参考图只接受公网 http/https URL
参考图最多 8 张
提示词总文本长度最多 4000 字符
解压后的请求体最多 2 MB
支持 Content-Encoding: gzip 和 Content-Encoding: br

最小请求示例

bash

curl -X POST "https://async.xinbao-ai.com/v1beta/models/gemini-3-pro-image-preview:generateContent" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "生成一张黄色香蕉产品图，纯色背景，棚拍光效。" }
        ]
      }
    ],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {
        "output": "url"
      }
    }
  }'

提交成功响应

json

{
  "id": "img_ad66v4mnqyzdtfw4",
  "object": "image.task",
  "model": "gemini-3-pro-image-preview",
  "status": "accepted",
  "polling_url": "/v1/tasks/img_ad66v4mnqyzdtfw4",
  "content_url": "/v1/tasks/img_ad66v4mnqyzdtfw4/content"
}

以上为 2026-03-21 使用测试 key 的真实提交结果，对应 HTTP 状态码为 202 Accepted。

2. 查询单个任务

端点

text

GET /v1/tasks/{id}

状态集合

text

accepted | queued | running | succeeded | failed | uncertain

轮询建议

推荐客户端默认策略：提交后先等 50s
之后按固定 10s 节拍轮询
如果服务端返回更大的 Retry-After，优先遵守更大的值
客户端总超时建议设置为 1200s
建议客户端提供“手动刷新 / 手动轮询”按钮，避免用户只能被动等待
不要把多个任务绑成高频死循环轮询

3. 批量查询多个任务

端点

text

POST /v1/tasks/batch-get

请求头

http

Authorization: Bearer <API_KEY>
Content-Type: application/json

请求体

json

{
  "ids": ["img_a", "img_b", "img_c"]
}

关键约束

ids 必须是非空数组
单次最多查询 100 个任务
重复 ID 会按首次出现顺序去重
只会返回当前 Authorization 对应 owner 下可见的任务
不存在或不属于当前 owner 的任务都会统一返回 not_found
返回体里的 items[*] 字段风格尽量与 GET /v1/tasks/{id} 保持一致

请求示例

bash

curl -X POST "https://async.xinbao-ai.com/v1/tasks/batch-get" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["img_ad66v4mnqyzdtfw4", "img_k3j5n8q2r1", "img_missing"]
  }'

返回示例

json

{
  "object": "batch.task.list",
  "items": [
    {
      "id": "img_ad66v4mnqyzdtfw4",
      "object": "image.task",
      "model": "gemini-3-pro-image-preview",
      "created_at": 1774105601,
      "status": "running"
    },
    {
      "id": "img_k3j5n8q2r1",
      "object": "image.task",
      "model": "gemini-3-pro-image-preview",
      "created_at": 1742486400,
      "finished_at": 1742486412,
      "status": "succeeded",
      "candidates": [
        {
          "content": {
            "parts": [
              {
                "inlineData": {
                  "mimeType": "image/png",
                  "data": "https://cdn.example.com/generated/demo.png"
                }
              }
            ]
          },
          "finishReason": "STOP"
        }
      ]
    },
    {
      "id": "img_missing",
      "object": "image.task",
      "status": "not_found",
      "error": {
        "code": "not_found",
        "message": "task not found"
      }
    }
  ],
  "next_poll_after_ms": 10000
}

批量轮询建议

多个进行中任务应尽量对齐到统一节拍
推荐固定按 10s 一个轮询周期发送 batch 请求
每轮只查询仍处于 accepted / queued / running 的任务
如果任务总数超过 100，请拆成多个 batch，但保持在同一个轮询周期里发送
如果服务端返回更大的 next_poll_after_ms，优先遵守更大的值
同一个 batch 不要高频重复查询，否则仍可能触发 429 rate_limited

查询示例

bash

curl -X GET "https://async.xinbao-ai.com/v1/tasks/img_k3j5n8q2r1" \
  -H "Authorization: Bearer <API_KEY>"

实测中的运行中状态

同一任务在提交后立刻轮询，返回 HTTP 200，状态为 running：

json

{
  "id": "img_ad66v4mnqyzdtfw4",
  "model": "gemini-3-pro-image-preview",
  "status": "running",
  "finished_at": null,
  "candidates": null,
  "error": null
}

这说明刚提交后立即轮询并不一定报错，也可能直接进入 running。但生产接入仍建议优先遵守 Retry-After。当前默认配置建议值为 10 秒。

成功完成响应

json

{
  "id": "img_k3j5n8q2r1",
  "object": "image.task",
  "model": "gemini-3-pro-image-preview",
  "created_at": 1742486400,
  "finished_at": 1742486412,
  "status": "succeeded",
  "response_id": "resp_123",
  "model_version": "gemini-3-pro-image-preview",
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "已生成图片。"
          },
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "https://cdn.example.com/generated/demo.png"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ]
}

失败响应示例

json

{
  "id": "img_ad66v4mnqyzdtfw4",
  "model": "gemini-3-pro-image-preview",
  "status": "failed",
  "finished_at": 1774105665,
  "candidates": null,
  "error": {
    "code": "upstream_timeout",
    "message": "upstream request timed out"
  }
}

这是同一任务在稍后继续轮询拿到的真实失败结果。也就是说，任务提交成功并不代表上游一定能产出最终图片，失败阶段可能出现在上游执行过程中。

同日复测成功样本（2026-03-21）

同一天再次使用测试 key 并行提交了 4 笔最小文本生图任务，四笔都返回 HTTP 202，任务 ID 分别为：

img_ilvpa3r4csdjcpf7
img_oxmuiof4tibjtjuw
img_dbnx7tntvhb67sxf
img_6p6narv3lp7pkpar

复测观察到的真实过程如下：

立即轮询时，4 笔任务都处于 running
t30s 时已有 1 笔进入 succeeded
t60s 时已有 2 笔进入 succeeded，访问 /content 返回 302
t120s 时 4 笔任务全部进入 succeeded

其中一笔成功任务在最终轮询时的关键字段如下：

json

{
  "id": "img_ilvpa3r4csdjcpf7",
  "status": "succeeded",
  "finished_at": 1774106773,
  "error": null,
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "inlineData": {
              "data": "https://d.uguu.se/ziYGQPeq.png"
            }
          }
        ]
      }
    }
  ]
}

对应的 /content 跳转样本：

https://d.uguu.se/ziYGQPeq.png
https://h.uguu.se/VaRrXlhm.png
https://h.uguu.se/QnzHMVXw.png
https://n.uguu.se/BVNgVmly.png

因此，目前更准确的结论是：异步生图链路已经确认既可能成功产出图片，也可能在某些请求上返回 failed/upstream_timeout。

多图参考图 20 并发压测（2026-03-21）

同一天进一步使用 3 张公网参考图作为输入，对异步生图执行了 20 并发压测。这轮压测的请求特点：

每个任务都带 3 张 inlineData.data = URL 参考图
20 个任务几乎同时提交
每个任务按 10s 节奏轮询

真实结果如下：

19/20 提交成功，返回 HTTP 202
1/20 在提交阶段直接出现链路层 SSL_ERROR_SYSCALL
最终 19/20 成功进入 succeeded
成功任务的 /content 全部返回 302
本轮没有出现 rate_limited
本轮没有出现 upstream_timeout

轮询阶段还观察到：

总轮询次数：944
其中 913 次返回 HTTP 200
31 次出现 HTTP 000，对应链路层 SSL_ERROR_SYSCALL
受链路抖动影响的任务数：16

成功任务的网关耗时分布：

最短：165s
平均：约 197.68s
最长：236s

因此在“多图参考图 + 20 并发”场景下，更准确的判断是：

业务层成功率很高，当前样本里成功提交后的任务全部最终出图
主要不稳定点在 TLS / 连接层，而不是业务返回 failed
接入侧应把 000 / SSL_ERROR_SYSCALL 视为可重试的链路层异常

典型参数错误示例

json

{
  "id": "img_k3j5n8q2r1",
  "object": "image.task",
  "model": "gemini-3-pro-image-preview",
  "status": "failed",
  "finished_at": 1742486408,
  "error": {
    "code": "invalid_request",
    "message": "reference image URL must use http or https"
  }
}

uncertain 表示请求可能已经发给上游，但网关无法可靠确认最终结果，调用方应结合业务幂等策略人工兜底。

4. 列出最近任务

端点

text

GET /v1/tasks

查询参数

days：查询最近几天，默认 3，最大 3
limit：返回条数，默认 20，最大 100
before_created_at：分页游标，Unix 秒
before_id：分页游标，必须和 before_created_at 一起使用

示例

bash

curl -X GET "https://async.xinbao-ai.com/v1/tasks?days=3&limit=20" \
  -H "Authorization: Bearer <API_KEY>"

返回示例

json

{
  "object": "list",
  "days": 3,
  "items": [
    {
      "id": "img_k3j5n8q2r1",
      "model": "gemini-3-pro-image-preview",
      "status": "succeeded",
      "created_at": 1742486400,
      "finished_at": 1742486412,
      "content_url": "/v1/tasks/img_k3j5n8q2r1/content"
    }
  ]
}

5. 获取最终图片跳转

端点

text

GET /v1/tasks/{id}/content

行为说明

成功时返回 302 Found
Location 指向首张图片 URL
未完成时返回 409 task_not_ready
只会跳转首张图，多图请读取任务详情

2026-03-21 的真实测试中，任务刚提交后立刻访问 /content，返回的就是 HTTP 409。

常见错误码

missing_api_key：缺少或非法的 Bearer Token
output_must_be_url：请求最终没有解析为 output=url
invalid_reference_image_url：参考图 URL 为空或不是绝对地址
invalid_reference_image_scheme：参考图不是 http/https
too_many_reference_images：参考图超过 8 张
prompt_too_long：提示词超过 4000 字符
request_too_large：解压后的请求体超过 2 MB
queue_full：任务队列已满，稍后重试提交
rate_limited：单任务轮询或同一批次批量轮询过快
task_not_ready：任务未完成就访问了 /content
upstream_timeout：任务已进入上游执行阶段，但上游超时未返回最终结果
auth_failed / insufficient_balance / upstream_rate_limited / upstream_error：上游执行阶段返回失败

异步图像任务 ​

适用场景 ​

整体流程 ​

1. 提交任务 ​

Base URL ​

端点 ​

鉴权 ​

关键约束 ​

最小请求示例 ​

提交成功响应 ​

2. 查询单个任务 ​

端点 ​

状态集合 ​

轮询建议 ​

3. 批量查询多个任务 ​

端点 ​

请求头 ​

请求体 ​

关键约束 ​

请求示例 ​

返回示例 ​

批量轮询建议 ​

查询示例 ​

实测中的运行中状态 ​

成功完成响应 ​

失败响应示例 ​

同日复测成功样本（2026-03-21） ​

多图参考图 20 并发压测（2026-03-21） ​

典型参数错误示例 ​

4. 列出最近任务 ​

端点 ​

查询参数 ​

示例 ​

返回示例 ​

5. 获取最终图片跳转 ​

端点 ​

行为说明 ​

常见错误码 ​

相关页面 ​

异步图像任务

适用场景

整体流程

1. 提交任务

Base URL

端点

鉴权

关键约束

最小请求示例

提交成功响应

2. 查询单个任务

端点

状态集合

轮询建议

3. 批量查询多个任务

端点

请求头

请求体

关键约束

请求示例

返回示例

批量轮询建议

查询示例

实测中的运行中状态

成功完成响应

失败响应示例

同日复测成功样本（2026-03-21）

多图参考图 20 并发压测（2026-03-21）

典型参数错误示例

4. 列出最近任务

端点

查询参数

示例

返回示例

5. 获取最终图片跳转

端点

行为说明

常见错误码

相关页面