Skip to main content
聊天类 API(LLM)是同步的——一次请求返回完整结果。但图像 / 视频 / 音乐生成都需要数秒到数分钟,走异步任务模式。

选哪种结果获取方式?

客户端轮询

创建任务后,定期 GET 任务状态直到完成。简单,适合脚本、CLI、Notebook、测试。

Webhook 回调

提交时传 callback_url,完成后我们 POST 结果给你。节省请求次数,适合生产服务。
两种可以同时用——传了 callback_url 也仍可主动查询任务结果。

创建任务

POST 提交后同步返回 200,主体里含 task_id
不同接口同步返回的字段不一样:
  • Midjourney / Suno 等支持「等到出结果再返回」的接口:直接给完整结果(图片 URL 等)
  • Veo / Sora 等重型视频接口:只回一个 task_id,结果稍后通过轮询或 Webhook 拿
具体看每个 API 的 API 参考

客户端轮询

通用模式(以 Midjourney /midjourney/tasks 为例):
注意/midjourney/tasks retrieve 返回的是 {id, request, response, created_at, started_at, finished_at, ...} 结构——没有 status 字段。判断「是否完成」请看 finished_at 是否存在,或 response 是否非空。其他服务的任务查询接口字段不完全相同,请参考各自 API 文档。 请合理控制轮询频率,避免触发 too_many_requests(429)。建议带退避,并优先依据具体接口的「典型耗时」估算等待。

Webhook 回调

callback_url 加到请求 body:
任务完成后,我们把结果 POST 到这个地址。回调主体形如: 成功:
失败:

Webhook 服务端要求

  • 必须是公网可达的 HTTPS(建议)URL
  • 收到回调请尽快返回 2xx,业务处理放后台
  • 回调当前不带签名头。请:
    • callback_url 包含一段不易猜的 token 路径段
    • 或在服务端用 task_id 比对自己之前创建任务时记下的 ID

最小示例(Flask)

选型对比

失败处理

不论用哪种方式,都可能拿到失败结果。失败响应的 error.code 与同步错误码一致——见 响应格式任务失败一般不扣费;具体策略以服务详情页为准。

下一步

响应格式

所有错误码与状态码

网关与认证

Token、域名、安全