异步任务与轮询
可靠流程是：提交一次 → 保存 task_id → 查询同一任务 → 校验图片 → 下载保存。轮询重试不应变成重新提交。
哪些方式会创建异步任务
| 提交方式 | 正常接纳 HTTP | 说明 |
|---|---|---|
/v1/images/generations/async |
202 | 推荐文生图 |
/v1/images/edits/async |
202 | 推荐图生图 |
/v1/image-tasks/generations、/edits |
202 | 兼容入口 |
普通 Images 路径 + background:true |
200 | JSON 必须是布尔 true；multipart 为文本 true |
普通 Images 路径 + task_type:"async" |
200 | 兼容开关 |
普通 Images 路径 + Prefer: respond-async |
200 | HTTP 请求头开关 |
普通路径返回 200 时，也可能是任务对象。应识别 task_id，不能仅凭状态码把响应当成图片。
background:"auto"/"opaque"/"transparent" 是背景相关字符串，不是异步开关。JSON 字符串 "true" 也不等于布尔 true。关闭异步时省略兼容开关；要同时表达背景字符串和异步，请使用 /async 路径，背景能力仍取决于渠道。
查询入口与归属
推荐 GET /v1/images/tasks/{task_id}。以下是同一任务的查询别名：
text
/v1/image-tasks/{task_id}
/v1/images/generations/{task_id}
/v1/images/edits/{task_id}
/v1/tasks/{task_id}
必须携带创建任务时的同一 API Key。缺少 Key、Key 不匹配、任务不存在或已清理，都可能返回 404。不要仅凭 404 断定模型故障。
响应字段
| 字段 | 类型 | 说明 |
|---|---|---|
| id / task_id | string | 本站任务 ID，优先保存 task_id |
| object | string | 图片任务通常为 image.generation.task |
| status | string | 对外状态，见下表 |
| state | string | 兼容状态，如 queued/running/succeeded/failed |
| provider_status | string | 另一套兼容状态，如 in_progress/completed |
| poll_url / poll_path | string | 查询地址/路径；不要向不可信外域转发 Key |
| poll_after_ms | number | 建议轮询间隔，当前默认 3000 毫秒 |
| created_at / updated_at | number | Unix 秒时间戳，部分响应还有 created |
| completed_at / expires_at | number | 终态时间/过期时间，可能未出现 |
| data | array | 成功后的图片列表，应检查非空 |
| result | object 或其他值 | 兼容结果；正常图片结果通常包含 result.data |
| request_id | string，可选 | 请求关联 ID，不保证所有阶段都有 |
| billing | object，可选 | 网关推断的账务提示，不代替账单 |
| error | object，可选 | 通常包含 message |
| submission_uncertain | boolean，可选 | true 表示结果未知，应核对而非自动重提 |
状态处理
| status | 含义 | 客户端动作 |
|---|---|---|
| processing | 排队或生成中 | 按间隔 GET 查询 |
| completed | 任务层报告完成 | 检查 data/result.data 非空、图片能读取后才视为业务成功 |
| failed | 失败或提交不确定 | 停止轮询，读取错误及 submission_uncertain |
| cancelled | 取消终态兼容值 | 停止轮询；不表示当前开放了取消 API |
| expired | 过期终态兼容值 | 停止轮询；过期任务也可能直接 404 |
兼容旧客户端时可同时识别 state 的 succeeded，但不要漏掉正式对外的 completed。未知状态不能无限等待，应受客户端总截止时间控制。
完成与失败的结构示意
json
{
"task_id": "imgtask_example",
"status": "completed",
"state": "succeeded",
"data": [{"url":"https://api.manxiaobai.online/generated/example.png"}],
"result": {"data":[{"url":"https://api.manxiaobai.online/generated/example.png"}]},
"billing": {"status":"charged"}
}
json
{
"task_id": "imgtask_example",
"status": "failed",
"state": "failed",
"error": {"message":"本次请求失败，请结合 request_id 核对原因"}
}
示例中的任务、链接与错误文字均为结构示意。HTTP 200 的查询响应可以承载失败任务，不能只检查 HTTP 状态。
重试、超时与保存
- 当前没有可依赖的
Idempotency-Key去重保证，重复提交可能产生多个任务和多次扣费。 - 只对网络中断、429 或临时 5xx 的 GET 查询做有界退避；遵循 Retry-After，避免高频轮询。
- 提交失败且没有任务 ID 时，记录时间与错误，先核对调用记录。不要把“没收到响应”等同于“没创建任务”。
- 客户端等待到期时保存任务 ID，之后继续查同一个任务；等待超时不是取消操作。
- 当前终态任务保留设置为约 2 小时，图片也属于临时托管。及时下载，不把任务表和临时 URL 当作永久存储。
- 在途任务不保证跨服务重启自动恢复；长时间 processing 应携带 ID 联系支持。当前没有公开取消接口。