必须通过任务id轮询get接口获取status和video_url;创建任务后提取32位id,用其请求https://ark.cn-beijing.volces.com/api/v1/videos/{id},鉴权通过且status为succeeded时,立即获取24小时内有效的video_url。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

你想在调用Seedance视频生成API后,准确知道任务是否完成、有没有出错、视频URL能不能用了——不是靠刷新网页猜,而是用程序主动查,拿到确切的status和video_url。这一步漏掉,后面所有下载、转存、嵌入都无从谈起。
获取任务ID
调用创建视频任务接口(POST /api/v1/videos)成功后,响应体中必须提取 【id】 字段值。这个ID是后续所有状态查询的唯一钥匙,不能用模型名、提示词或时间戳代替。
注意:该ID由火山引擎服务端生成,长度固定为32位小写字母+数字组合,例如 6a2f8c1e9d4b3a7f0c8e2d1b5a9f4c6。若响应中没有id字段,说明任务创建失败,不要继续查状态。
构造查询请求
向 GET https://ark.cn-beijing.volces.com/api/v1/videos/{id} 发起HTTP请求,其中 {id} 替换为你上一步拿到的真实任务ID。
必须在Header中携带 Authorization: Bearer YOUR_API_KEY,且YOUR_API_KEY必须与创建任务时使用的完全一致。密钥不匹配将返回401错误,且不会提示具体是哪个密钥失效。
Endpoint中的 cn-beijing 是强制区域标识,不可替换为其他地域如 cn-shanghai 或 global,否则请求直接被拒绝。
解析返回结果并判断状态
第一步:检查HTTP状态码。200表示接口可通、鉴权通过;404表示任务ID不存在或已过期(仅保留7天);401/403说明API Key无效或权限不足。
第二步:读取响应JSON中的 status 字段值,按以下逻辑分支处理:
• queued 或 running:任务尚未完成,需等待后重试。建议间隔3秒以上再发起下一次查询,高频轮询会触发限流(单IP每分钟最多30次)。
• succeeded:任务成功,立即读取 content.video_url。该URL有效期仅24小时,【必须在获取后10分钟内发起下载请求】,否则可能因CDN缓存更新导致链接失效。
• failed 或 expired:任务异常终止。此时应读取 error.message 内容,常见原因包括提示词含违禁词、分辨率参数超出模型支持范围、参考图格式损坏等。
• cancelled:仅当主动调用取消接口后出现,表示任务被人工中止,无视频产出。











