长时间视频任务：用 Webhook 回调还是轮询

在 RelayDance（OpenAI 兼容的视频生成 API）上处理长时间视频任务时，可以选择两种方式获取结果：轮询或 Webhook 回调。轮询是提交任务后用 GET /v1/video/generations/{task_id} 反复查询，直到 status 变为 succeeded 或 failed；Webhook 则是在 metadata.callback_url 设置回调地址，任务最终状态由服务端主动 POST 到你的服务器。短脚本或交互场景适合轮询，后台批量或长任务更适合 Webhook。

轮询模式的工作流程

轮询适合实现简单、无需对外暴露服务器的场景。首先用 POST /v1/video/generations 提交任务，请求体包含 model、prompt、seconds 和 metadata（ratio、resolution、generate_audio 等）。接口返回 task_id 后，使用 GET /v1/video/generations/{task_id} 定期查询任务状态。当 status 为 succeeded 时，响应结果中包含可下载的 video url；若为 failed 则表示生成失败。轮询的优点是调试直观，缺点是需要客户端持续发起请求，对于较长的 clips（最长 15 秒）可能产生较多查询次数。详细字段说明见 https://relaydance.com/docs。

Webhook 回调模式的工作流程

Webhook 模式适合后台服务和长时间任务，避免持续轮询带来的额外请求。提交任务时在 metadata 中设置 callback_url，指向你自己服务器上的接收端点。任务完成后（无论成功或失败），RelayDance 会将最终状态以 POST 请求发送到该地址，你的服务器据此处理后续逻辑，例如保存 video url 或触发通知。这种方式无需客户端反复查询，更节省资源，但要求你的服务器具备公网可访问的接收端点，并能正确解析回调负载。两种模式可根据业务需要灵活选用。

两种模式对比

提交长时间视频任务的步骤

1. 在 https://relaydance.com/console 创建 API Key，并以 Authorization: Bearer YOUR_API_KEY 鉴权。
2. 向 https://relaydance.com/v1/video/generations 发送 POST 请求，填写 model、prompt、seconds 和 metadata。
3. 如需参考媒体，将其放入 metadata.content[]，并在 prompt 中用 @image1 到 @imageN 引用（每次请求最多 9 张参考图、3 段参考视频、3 条音轨）。
4. 选择获取结果的方式：轮询 GET /v1/video/generations/{task_id}，或设置 metadata.callback_url 使用 Webhook。
5. 读取最终结果中的 video url。失败或出错的请求不计费。

计费与可用模型

RelayDance 提供多组视频和图像模型，包括 ByteDance Seedance 2.0、Seedance 1.5 Pro、HappyHorse 视频模型，以及 Grok Imagine 的视频和图像模型与 Grok 文本模型。图像生成使用 POST /v1/images/generations。主流模型组的价格相比官方列表价低 30% 或更多，且失败或错误的请求从不计费，这对反复轮询的长任务尤为重要。支付方式支持 USDT 和 Stripe 信用卡。各模型的实时单价请查看 https://relaydance.com/models。

常见问题（FAQ）

问：轮询和 Webhook 可以同时使用吗？

答：两者都基于同一次任务提交。即使设置了 callback_url，你仍可通过 GET /v1/video/generations/{task_id} 查询状态，可按业务需要组合使用。

问：单个视频 clip 最长能生成多久？

答：clips 最长可达 15 秒，长度通过提交任务时的 seconds 参数控制。

问：轮询时多次查询会被收费吗？

答：计费基于生成任务本身，失败或错误的请求从不计费。具体的实时单价请参见 https://relaydance.com/models。