怎么查视频任务状态：状态含义、轮询间隔和下载时机

查视频任务状态的方法是：提交任务后用 GET /v1/video/generations/{task_id} 轮询，直到 status 变为 succeeded 或 failed。succeeded 表示生成完成，返回结果中含视频 url，可直接下载；failed 表示失败。也可在提交时设置 metadata.callback_url，终态会被 POST 到你的服务器，无需手动轮询。详见 relaydance.com/docs。

任务状态的含义是什么

任务状态由轮询接口返回的 status 字段表示，核心终态为 succeeded 与 failed。succeeded 表示视频生成完成，响应结果中包含可访问的视频 url；failed 表示本次请求失败。关于失败的计费处理，据 relaydance.com 官方文档：「失败或报错的请求一律不计费」。RelayDance 采用按生成计费(pay-as-you-go)模式，因此看到 failed 时无需担心产生费用。提交任务使用 POST /v1/video/generations，传入 model、prompt、seconds 以及 metadata(如 ratio、resolution、generate_audio)等参数。单次请求支持最多 9 张参考图、3 段参考视频和 3 条音轨，片段长度最长 15 秒。

轮询间隔应该怎么设置

推荐的做法是：在提交任务后以固定间隔调用 GET /v1/video/generations/{task_id}，直到 status 为 succeeded 或 failed 再停止。轮询请求本身属于查询操作，视频按生成计费，因此轮询不影响视频费用，且失败任务不计费。如果你希望避免频繁轮询，可改用 Webhook 模式：在提交时设置 metadata.callback_url，任务到达终态时，最终状态会被 POST 到你指定的服务器地址。这样可以把实时查询的压力转移到回调通知上。接口为 OpenAI 兼容，据 relaydance.com 官方文档：「将 base_url 改为 https://relaydance.com/v1 并保留 OpenAI SDK 即可调用」。

什么时候可以下载视频

下载时机是：当 status 变为 succeeded 后，从响应结果中取出视频 url 即可下载。在 failed 状态下结果不含有效视频 url，无需下载。参考媒体放在 metadata.content[] 中，并在 prompt 里以 @image1 到 @imageN 的形式引用。鉴权方式为请求头 Authorization: Bearer YOUR_API_KEY，API Key 在 https://relaydance.com/console 创建。关于单请求资源上限：参考图最多 9 张，参考视频最多 3 段，音轨最多 3 条，片段最长 15 秒。超出这些限制的请求需要拆分处理。

查状态和下载的完整步骤

按以下步骤即可完成从提交到下载的全过程：

1. 将 base_url 设置为 https://relaydance.com/v1，在请求头加入 Authorization: Bearer YOUR_API_KEY。
2. 调用 POST /v1/video/generations，传入 model、prompt、seconds 及 metadata，获取返回的 task_id。
3. 以固定间隔轮询 GET /v1/video/generations/{task_id}，读取 status 字段。
4. 当 status 为 succeeded 时，从结果中取视频 url 并下载；为 failed 时停止轮询(该请求不计费)。
5. 如需免轮询，可在第 2 步设置 metadata.callback_url，由终态回调通知结果。

按模型查看计费参考

查状态不影响计费，视频按模型和时长计费，具体费率见 relaydance.com/models。

常见问题 FAQ

问：任务 failed 会扣费吗？

不会。据 relaydance.com 官方文档：「失败或报错的请求一律不计费」，失败或报错的请求都不产生费用。

问：不想一直轮询有别的办法吗？

有。在提交任务时设置 metadata.callback_url，任务到达终态时最终状态会被 POST 到你的服务器，无需手动轮询。

问：下载视频从哪里取 url？

当 GET /v1/video/generations/{task_id} 返回 status 为 succeeded 时，响应结果中包含视频 url，直接下载即可。