轮询视频任务返回 404 not found：task id 查不到的常见原因

轮询 GET /v1/video/generations/{task_id} 返回 404 not found，通常说明查询请求没有对准一个存在的任务。常见原因有四类：base_url 没有改为 https://relaydance.com/v1；查询路径拼写错误；task_id 取值有误，例如取错字段或带入多余字符；提交阶段已经报错，任务从未创建。按这四点逐项核对，可以定位大多数问题。

原因一：base_url 或查询路径不正确

如果 base_url 仍指向其他服务商，或者路径写错，服务端就找不到对应任务，因此返回 404。RelayDance 采用 OpenAI 兼容协议，据 relaydance.com/docs 官方文档：「将 base_url 改为 https://relaydance.com/v1 并保留 OpenAI SDK 即可调用」。提交任务和查询任务需要使用同一个 base_url。完整的查询地址应为 https://relaydance.com/v1/video/generations/{task_id}。常见的写法错误包括：路径中出现两次 /v1，把 generations 写成单数，或者把视频任务误发到图像接口 POST /v1/images/generations。请求头中还需要携带 Authorization: Bearer YOUR_API_KEY，API Key 可以在 https://relaydance.com/console 创建。接口细节见 relaydance.com/docs。

原因二：task_id 取值错误或任务从未创建

task_id 必须直接取自 POST /v1/video/generations 的成功响应，并且原样使用。提交请求需要包含 model、prompt、seconds 和 metadata（其中可设置 ratio、resolution、generate_audio、callback_url 和 content[]）。如果提交时已经返回错误，就不会产生任务，拿任何 id 去查询都会是 404。下面这些情况需要特别留意：

• 参考媒体放在 metadata.content[] 中，并在 prompt 里用 @image1 到 @imageN 引用。
• 每个请求最多可附带 9 张参考图、3 段参考视频和 3 条音轨。
• 单条视频时长最长 15 秒。

超出上述限制，或者 JSON 结构有误，都可能导致提交失败。因此，在开始轮询之前，应先确认提交接口返回了成功状态和 task_id。

排查步骤：从提交到拿到视频 url

建议按固定顺序排查，先确认任务确实创建成功，再检查查询请求本身。

1. 打印提交接口的完整响应，确认其中包含 task_id，且没有错误字段。
2. 检查查询请求使用的 base_url 是否为 https://relaydance.com/v1，并且与提交时一致。
3. 核对查询路径 /v1/video/generations/{task_id} 的拼写，确认 id 前后没有空格或引号。
4. 确认请求头使用 Authorization: Bearer YOUR_API_KEY。
5. 持续轮询，直到 status 变为 succeeded 或 failed。成功时，结果中会包含视频 url。
6. 如果不想轮询，可以设置 metadata.callback_url，任务的最终状态会以 POST 请求推送到你的服务器。

404 或失败请求会产生费用吗

不会。据 relaydance.com 官方文档：「失败或报错的请求一律不计费」。计费方式为按生成的视频按量付费，只有成功生成的视频才会计费。参考价格如下，实时费率以 relaydance.com/models 为准：

以 Seedance 2.0 720p 为例，一条 15 秒的视频约为 $2.85。平台支持 USDT 和 Stripe 银行卡付款。

常见问题

问：提交成功后立刻查询返回 404，是任务丢了吗？

答：请先确认查询时使用的 base_url 和路径与提交时一致，并且 task_id 是从提交响应中原样取得的。多数情况下是这两处不一致导致的。

问：能否避免频繁轮询？

答：可以。在 metadata.callback_url 中填写你的服务器地址，任务的最终状态会以 POST 请求推送过去。

问：使用 RelayDance 需要 BytePlus 企业账户或 KYC 吗？

答：不需要。只要通过 OpenAI 兼容接口，将 base_url 设为 https://relaydance.com/v1，即可调用 Seedance。