统一异步任务接口提供标准化的提交 → 轮询 → 获取结果流程,屏蔽不同厂商 API 差异。
概述
视频生成、图片生成、音乐生成等 AI 任务通常需要几十秒甚至数分钟才能完成。为保障用户体验与系统稳定性,这些任务统一通过异步任务接口处理:- 提交任务 — 发送生成请求,立即获得任务 ID
- 查询状态 — 使用任务 ID 轮询进度,或通过回调地址接收通知
- 获取结果 — 任务完成后从响应中获取生成的资源 URL
提交任务
POST /v1/task/submit请求参数
请求示例
响应示例
查询任务
GET /v1/task/{task_id}请求示例
响应示例
任务进行中:任务状态
回调通知
提交任务时传入callback_url,当任务状态发生变更时,系统会向该地址发送 POST 请求,请求体与查询接口响应格式一致:
X-Billing-Detail: true 的话,任务结束时的回调请求会带上 X-Billing-Currency、X-Billing-Amount 两个请求头,给出这个任务的 实际扣费。
完整轮询示例
响应字段说明
用量信息 (Usage)
任务进入终态(completed / failed)后,部分模型会在响应中返回 usage 字段,反映本次任务的实际资源消耗。usage 是一个 标签联合(tagged union):通过 type 字段区分计量单位。
type=tokens(按 token 计费)
适用于 Doubao / Vidu / Ali / Kling 文本类、Gemini 等按 token 计费的任务:type=duration(按时长计费)
适用于 Sora / Xai-video 等按生成视频时长计费的任务:type=call(按次计费)
适用于 Midjourney、Suno、可灵视频等按次计费的任务,只在任务成功(completed)时返回:
multiplier 由请求参数与实际产出决定,例如 Midjourney 高清(--hd)为 2,V7 草图为 0.5,视频按分辨率和条数计;实际交付数量少于请求时按交付数量计(如只出了 4 张的 V8 草图为 0.5)。按积分、张数、首数计价的模型(如可灵、Vidu 按积分),multiplier 就是这次消耗的数量。
multiplier 只描述规格,同一个请求不管谁调用都相同:不含分组折扣、个人折扣等账户相关的价格调整,也不含参考图费用这类另外加收的费用。要核对每个任务实际扣了多少钱,请使用 实际扣费。
- 按上游实际费用结算的任务(如 Flux)不返回
usage字段 - 按次计费的任务失败时全额退款,不返回
usage - 任务在
queued/in_progress状态时不会返回usage - 历史任务或上游未返回用量数据的任务也会省略此字段
- 字段值为 0 的子项(如
text_tokens: 0)会被省略
实际扣费
查询任务时在请求头里加上X-Billing-Detail: true,任务结束后响应会多两个响应头,给出这个任务实际扣了多少钱。折扣、附加费、失败退款都已经算在里面,和账单上的金额一致。响应内容不变。
cURL
金额按模型定价的币种给:人民币定价的模型是人民币元,美元定价的模型是美元。请直接使用返回的金额,不要自己按汇率换算。
提交任务时也带上
X-Billing-Detail: true 的话,之后查询不带这个请求头也会返回这两个响应头;任务结束时的回调请求也会带上这两个请求头。
适用范围
所有一次查一个任务的查询接口都支持:本页的GET /v1/task/{task_id},以及各家官方格式的任务查询接口,包括 Midjourney(/midjourney/task/{task_id} 与 /mj/task/{id}/fetch)、OpenAI 视频格式 GET /v1/videos/{id}、可灵、MiniMax、Suno、Luma、Runway、Replicate、Flux、Vidu、豆包、阿里百炼、Ideogram、Mureka、xAI 视频、Gemini 原生格式的 Veo 视频。官方格式接口的响应内容保持官方原样,金额只在响应头里。
一次查多个任务的接口不返回,例如 Suno、Luma 的批量查询和 Midjourney 按条件查询;可灵新版查询 GET /kling/tasks?task_ids= 只填一个任务时返回。
上面这些任务,提交时带了 X-Billing-Detail: true 的,任务结束时的回调请求都会带上这两个请求头,回调内容不变。
- 只在任务结束(
completed/failed)后返回;失败的任务费用已退回时金额为0 - 任务刚结束、结算还没完成的极短时间内可能暂时没有这两个头,稍后再查一次即可
- 不带
X-Billing-Detail: true(提交时也没带)时不返回 - 在浏览器里调用时,这两个响应头可以直接读取
Flux 模型的完成通知
- 想在任务结束时收到通知,请在请求体顶层传
callback_url,所有 Flux 模型都支持。 input里的webhook_url/webhook_secret不会发给上游。flux-3-image、flux-3-video、flux-tools/video-edit-v1、flux-tools/outpainting-v1的官方接口不接受回调字段,带了也会被忽略,请用callback_url或轮询。- 不传回调时,提交后用
GET /v1/task/{task_id}轮询(建议间隔 3~10 秒;视频任务通常需要几分钟)。
注意事项
相关链接
视频模型
各视频模型的官方 API 格式文档
图片模型
各图片模型的 API 格式文档