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

对于长时间视频生成任务，RelayDance 提供两种获取结果的方式：轮询 (polling) 与 Webhook 回调 (callback)。轮询通过 GET /v1/video/generations/{task_id} 反复查询任务状态，直到 status 变为 succeeded 或 failed；Webhook 则在 metadata 中设置 callback_url，任务完成后由 RelayDance 将最终状态 POST 到你的服务器。短任务或调试可用轮询，长任务和批量处理更适合 Webhook。

轮询与 Webhook 该如何选择

选择依据是任务时长与你的服务架构：轮询适合调试和短片段，Webhook 适合长时间批量任务。轮询需要客户端持续发起请求，逻辑简单但会占用连接；Webhook 由服务端主动推送，节省客户端资源，但要求你有可公开访问的接收端点。RelayDance 单个请求支持最长 15 秒的片段 (clips up to 15 seconds)，并可携带最多 9 张参考图、3 段参考视频和 3 条音轨。任务量大时，逐个轮询会带来额外请求开销，此时 Webhook 回调更合适。两种方式返回的结果都包含视频 url。

如何提交并轮询一个视频任务

提交任务使用 POST /v1/video/generations，轮询使用对应的 GET 接口，步骤如下：

1. 发送 POST /v1/video/generations，传入 model、prompt、seconds 及 metadata (ratio、resolution、generate_audio 等)。
2. 从响应中取得 task_id。
3. 调用 GET /v1/video/generations/{task_id} 查询状态。
4. 当 status 为 succeeded 时，从结果中读取视频 url；若为 failed 则处理错误。

参考媒体放入 metadata.content[]，并在 prompt 中以 @image1 到 @imageN 引用。认证方式为 Authorization: Bearer YOUR_API_KEY，可在 https://relaydance.com/console 创建密钥。

Webhook 回调如何配置

Webhook 通过设置 metadata.callback_url 启用，任务结束后最终状态会被 POST 到该地址。这种方式省去了客户端反复查询的过程，适合处理长时间或大批量任务。RelayDance 采用 OpenAI 兼容协议，据 relaydance.com/docs 官方文档：「将 base_url 改为 https://relaydance.com/v1 并保留 OpenAI SDK 即可调用」。这意味着你无需 BytePlus 企业账号或 KYC，即可通过熟悉的 SDK 接入 Seedance。接入时把 base_url 指向 https://relaydance.com/v1，在请求 metadata 中填入你的 callback_url，即可切换到回调模式，无需改动 SDK 本身。

失败计费与两种模式对比

无论使用轮询还是 Webhook，计费规则一致：只对成功生成的视频按量计费。据 relaydance.com 官方文档：「失败或报错的请求一律不计费」，因此选择哪种获取方式都不会影响失败任务的费用。以下为常见模型的参考价格与两种模式对比：

价格参考 (来源 https://relaydance.com/models)：Seedance 2.0 720p 约 $0.190 / 秒，1080p 约 $0.470 / 秒，Seedance Fast 约 $0.152 / 秒，原生 4K 约 $4.90 / 5 秒条。支付方式为 USDT 与 Stripe 卡，按量付费。

常见问题 FAQ

1. 长时间任务超时怎么办？ 建议使用 Webhook 回调：在 metadata.callback_url 中填入你的接收地址，任务完成后最终状态会被 POST 过去，无需客户端长时间保持轮询连接。

2. 任务失败会扣费吗？ 不会。据 relaydance.com 官方文档：「失败或报错的请求一律不计费」，无论轮询还是 Webhook 都遵循此规则。

3. 切换到 RelayDance 需要改代码吗？ 接口为 OpenAI 兼容，只需将 base_url 改为 https://relaydance.com/v1 并保留原有 OpenAI SDK，具体见 https://relaydance.com/docs。