错误与排错

出错时先来这一页对表，找到原因和处理办法；末尾的「使用提示」汇总了几个常见的用法问题。

HTTP 状态码

请求本身出错时，返回 4xx 状态码，响应体是 JSON，用 error.code 和 error.message 说明原因。例如令牌错误时：

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: …)"
  }
}

常见情况对照：

场景	HTTP	code	message（节选）	怎么办
不带令牌，或令牌错误	401	（空）	Invalid token (request id: …)	检查请求头是否为 Authorization: Bearer <API 密钥>，密钥是否复制完整
额度不足（含预扣不足）	403	permission_denied	提示额度不足：密钥额度不够时为 token quota is not enough, …，账户余额不够时为 Not enough quota to pre-consume for this request: …	提高这把密钥的额度，或补充账户余额
缺少 content	400	invalid_request	content is required	补上 content 数组
模型名不存在	400	invalid_request	提示该模型不可用	核对模型 ID，见模型与规格
请求体不是合法 JSON	400	invalid_request	invalid character …	检查 JSON 格式，如引号、逗号
分辨率不支持	400	invalid_request	提示该模型不支持此分辨率	换成该模型支持的分辨率，如 2.5 不支持 4k
传了模型不提供的参数（如 seed）	400	invalid_request	提示参数不受支持	去掉该参数，见下文「使用提示」
查询的任务不存在	404	task_not_found	Task not found	核对任务号
服务端错误或网络超时	5xx		服务暂时不可用	稍后重试；重试创建前，先确认上一次是否已经返回任务号，避免重复创建

请求被拒绝（4xx、5xx）时不扣费，已预扣的费用会自动退回。

任务级失败

任务创建成功后，生成过程中也可能失败。这时查询接口里 status 是 failed，并带有 error.code 和 error.message，格式见查询任务与获取视频。以官方规格为准

常见原因有：

• 参考素材的链接无法下载，比如链接失效、需要登录或不是公网可访问的。
• 内容审核没有通过。
• 参考图或参考视频里含有真人肖像。

处理办法：检查素材链接是否公网可访问、内容是否合规，换一份素材后重新创建任务。失败的任务不收费，已预扣的费用自动全额退回。

排错清单

请求报错或结果不对时，按顺序检查：

1. 密钥与分组：请求头是否带了 Authorization: Bearer <API 密钥>；密钥的分组是否选了「Seedance视频分组」或 auto。
2. 模型 ID：是否写了带日期的完整 ID，和模型与规格一致。
3. 分辨率：是否在该模型支持的范围内（2.0 支持 4k，2.5 不支持）。
4. 时长：Seedance 2.0 取 4–15 秒，2.5 取 4–30 秒，或填 -1。
5. 参数：有没有传 2.0 / 2.5 模型不提供的参数，比如 seed。
6. 素材链接：参考素材是否是公网可访问的 HTTPS 地址，在任务完成前一直有效。
7. 额度：这把密钥的额度和账户余额，是否够这一单的预扣，带参考视频的请求预扣更高，见价格与计费。
8. 接口格式：如果用的是兼容接口，参数是否错放到了顶层，见兼容接口。
9. 没拿到任务号：创建请求超时或连接中断时，先到控制台「常规 → 任务日志」确认任务有没有生成，再决定要不要重发，避免重复扣费。

还是找不到原因时，把任务号、请求时间和返回的 code、message 记下来，在控制台的「任务日志」和「使用日志」里核对。

使用提示

场景	本站做法
查看全部任务	控制台「常规 → 任务日志」可查看全部任务的状态、耗时与视频，每单费用见「使用日志」；程序里保存创建时返回的任务号即可随时查询。SDK 的 tasks.list 对应的接口本站未开放（返回 404）
任务提交之后	任务会直接开始生成并由平台跑完，失败和超时自动全额退款；SDK 的 tasks.delete 对应的接口本站未开放（返回 404），提交前请确认参数
参考素材	把公网可访问的 HTTPS 链接直接写进 content，无需预先上传或入库
获取结果	通过查询接口获取，建议每 10–15 秒查询一次，无需传 callback_url
随机种子 seed	seed 是 Seedance 1.x 的参数，2.0 / 2.5 模型本身不提供；传入会返回 400，不扣费
其他方舟参数	draft、output_format、priority、execution_expires_after、service_tier 以火山方舟官方规格为准
本线路的型号	Seedance 2.0 与 2.5 视频生成；2.0 最高 4k，2.5 最高 1080p，见模型与规格