POST /v1/videos 后,保存响应中的公开任务 id。查询与下载均使用该 ID,并携带有权访问该任务的平台 API Key。
查询任务
状态与后续动作
建议从每 3 秒查询一次开始,并给自己的客户端设置总等待时限。发生限流时降低查询频率。客户端等待超时不代表生成失败,保存任务 ID 后仍可继续查询;不要自动重新提交生成任务。
查询结果可能暂时保留最近一次已知状态,不保证每次查询都能取得新的上游进度。查询接口找不到任务时,可能返回 HTTP
400 和 task_not_exist;不要只用 404 判断任务是否存在。
生成完成
以下示例仅展示关键字段,URL 和任务 ID 均为占位值:生成失败
查询请求本身可以返回 HTTP200,但任务状态为 failed。此时仍应按生成失败处理:
下载已完成的视频
确认任务已完成后,再请求内容接口:--fail 使 HTTP 错误返回非零退出码,避免把错误响应当成成功视频。检查退出码后再使用文件;网络中断可能留下不完整文件。
你也可以在自己的服务端获取 output.video_url 指向的资源。不要向第三方结果域名发送平台 API Key;带鉴权的 /content 接口用于通过网关访问结果。
内容接口在任务尚未完成时返回 HTTP 400,任务不存在或不可访问时返回 404。此接口的错误位于 error.message 和 error.type,不保证提供 error.code。
客户端处理流程
提交一次任务,保存id,然后只查询该任务。遇到 completed 时检查视频地址并下载;遇到 failed 时记录错误码并停止。其他状态不能当作成功。
连接超时、网络中断或暂时性服务错误并不能证明生成任务没有被受理。在没有明确结果时,应先核查已有任务和平台记录,再决定是否重新生成,避免重复提交和重复费用。