跳转到主要内容
统一异步任务接口提供标准化的提交 → 轮询 → 获取结果流程,屏蔽不同厂商 API 差异。

概述

视频生成、图片生成、音乐生成等 AI 任务通常需要几十秒甚至数分钟才能完成。为保障用户体验与系统稳定性,这些任务统一通过异步任务接口处理:
  1. 提交任务 — 发送生成请求,立即获得任务 ID
  2. 查询状态 — 使用任务 ID 轮询进度,或通过回调地址接收通知
  3. 获取结果 — 任务完成后从响应中获取生成的资源 URL

提交任务

POST /v1/task/submit

请求参数

请求示例

响应示例


查询任务

GET /v1/task/{task_id}

请求示例

响应示例

任务进行中:
任务完成(按 token 计费):
任务完成(按次计费):
任务完成(按时长计费):
任务失败:

任务状态


回调通知

提交任务时传入 callback_url,当任务状态发生变更时,系统会向该地址发送 POST 请求,请求体与查询接口响应格式一致:
提交任务时在请求头里带上 X-Billing-Detail: true 的话,任务结束时的回调请求会带上 X-Billing-Currency、X-Billing-Amount 两个请求头,给出这个任务的 实际扣费。
  1. 回调地址必须是公网可访问的 HTTPS 地址
  2. 回调请求超时时间为 10 秒
  3. 回调地址不能指向 localhost、127.0.0.1 或平台自身域名
  4. 即使设置了回调,仍建议实现轮询作为兜底,避免因网络原因错过通知

完整轮询示例


响应字段说明


用量信息 (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 秒;视频任务通常需要几分钟)。

注意事项

  1. 使用标准 Authorization: Bearer <API_KEY> 鉴权
  2. input 中的参数因模型而异,请在 模型列表 中点击对应模型查看详情文档
  3. 建议轮询间隔 3~10 秒,避免过于频繁的请求
  4. 任务结果中的资源 URL 可能有有效期限制,建议及时下载保存
  5. Flux 模型要接收完成通知请用顶层 callback_url,见上文「Flux 模型的完成通知」

相关链接

视频模型

各视频模型的官方 API 格式文档

图片模型

各图片模型的 API 格式文档