异步视频 API 至少有两个独立结果：任务是否已经提交，以及生成最后是否成功。把这两件事混为一谈，很容易产生昂贵的重试模式——应用看到响应慢或状态未完成，就再发一次 POST。第二次创建是另一个任务，不能用来刷新第一个任务。
接入应围绕已保存的任务 ID 来组织。把原始模型和参数、提交时间、任务回执与应用自己的业务编号一起保存。查询和下载都是对这个任务的读取操作。决定新建另一个视频之前，应先确认已有提交及其预留金额发生了什么。
先阅读响应，再修改请求
| 响应情况 | 检查什么 | 合理下一步 |
|---|---|---|
| 400 参数校验 | JSON、实际模型 ID、时长、分辨率 | 修正输入，保留任何已收到的任务 ID |
| 401 身份验证 | Authorization 请求头、有效 API Key | 使用自己控制台创建的密钥 |
| 403 权限或预留 | 启用 Seedance 的分组、余额、Key 额度 | 解决响应说明的原因后再创建 |
| 404 所属任务未找到 | 准确任务 ID、创建它的 Key | 修正查询，不为查询另建任务 |
| 409 内容未就绪 | 当前任务状态 | 继续查询原任务 |
| 5xx 服务或下载错误 | 已有回执与任务状态 | 按情况重试读取，先核对不确定的创建 |
这张表是排查分类，不意味着每个服务和每种失败都有完全相同的文本。请读取响应体，即使出现错误，只要拿到任务 ID 也要保存。缺少 Authorization 不能靠发送 Google 登录后的浏览器 cookie 解决；API 请求使用的是账号自己创建的 Bearer API Key。
参数错误应对照文档的 JSON。Seedance 2.0 接受 4–15 秒，2.5 接受 4–30 秒；当前两款产品都有 480p、720p 和 1080p 档位。模型展示名称代替实际 ID、不支持的时长，以及从别的服务猜来的接口路径，都可能让请求与本站契约不一致。
按合理间隔查询同一个任务
queued 和 running 是普通的中间状态。约每 15 秒查询一次，进入最终状态或需要核对时停止普通轮询逻辑。提前下载会返回未就绪错误，这不表示应该再创建一次视频。内容请求应由 succeeded 触发，而不是仅靠经过了多少秒。
全过程保持同一个 Key。另一个账号的 Key，或不是创建该任务的另一把 Key，不能替代任务所属密钥来读取。保存回执里的准确 ID，而不是猜测供应商的标识符。你的应用需要的是本站返回的本地任务 ID，这也是后续排查的关联依据。
API_KEY='YOUR_API_KEY'
API_BASE='https://seedancelink.io'
TASK_ID='REPLACE_WITH_RESPONSE_ID'
curl --fail-with-body "$API_BASE/api/v3/contents/generations/tasks/$TASK_ID" \
--header "Authorization: Bearer $API_KEY"区分待核对与没有收到回执
创建时收到 HTTP 202、needs_reconcile 和本站任务 ID，请保存并查询这个 ID。因为提交结果尚不确定，金额仍保留等待核对。不要将它变成自动新建的 POST，也不要在界面上显示成从未存在过任务。
如果网络中断，应用没有收到回执和任务 ID，则不要编造一个 ID，也不要假定请求根本没到服务端。保留请求详情和提交时间，把业务任务标记为未解决，确认情况后再决定是否重发。这样可以处理可恢复的不确定性，而不主动冒创建重复任务的风险。
用户切换页面后，应用应从自己的存储恢复任务记录。轮询进度的连接中断，可以恢复读取；重新连接并不需要重新创建视频。把这个规则写进重试逻辑，比让用户猜哪一次提交有效更可靠。
读取和创建应使用不同的重试规则
- 拿到任务 ID 后立即持久保存，再启动轮询。
- 查询和下载复用这个 ID，不用新的 POST 刷新进度。
- 未 succeeded 不下载，明确失败后先阅读原因再决定新任务。
- 日志保留安全的 ID、时间、状态和计费信息，不记录私有密钥。
- 无法解决的提交进入核对流程，不悄悄再创建一个任务。
排错常见问题
删除任务就能取消或退款吗？
这条流程不支持删除持久化视频任务，不要将 DELETE 请求当作取消或退款机制。
刷新网页会创建重复任务吗？
读取已保存的任务不会创建新任务。应用需要确保刷新或重试按钮不会重新发送创建 POST。
寻求支持时提供什么？
提供本站任务 ID、时间、模型、请求时长与分辨率、状态和安全的错误详情；不要提供 API Key。