Seedance API 接入教程：任务提交、轮询与结果下载（2026）

Seedance 视频生成采用异步任务制：创建任务的请求只返回一个任务 ID，视频不会同步出现在响应里。接入方需要自己查询状态、处理失败，并在结果链接过期前完成转存。

如果按 Chat Completions 的同步思路写代码，通常会在第一步就超时。本文按实际落地顺序，讲清 Base URL、鉴权、提交、轮询、下载、回调与幂等。

说明：Seedance、ByteDance、豆包、火山引擎、火山方舟等名称与商标归其权利人所有。本文仅作技术说明，不代表任何合作、代理或授权关系；接口路径、模型名称与价格以官方或站内文档为准。

一、接入参数：Base URL、模型与鉴权

火山方舟官方数据面 Base URL 为 https://ark.cn-beijing.volces.com/api/v3，创建视频任务的路径是 /contents/generations/tasks。鉴权使用 Authorization: Bearer $ARK_API_KEY，请求体为 JSON。

model 字段可以填 Model ID，也可以填 Endpoint ID。差异在于鉴权方式：使用 API Key 时通常两种都可用；使用 AK/SK 签名时一般必须填 Endpoint ID，不能直接填 Model ID。这是迁移和排错时最常见的坑之一。

接入前还要确认三件事：模型是否已开通、账号额度是否足够、当前通道是否支持你要用的时长与分辨率。网关用户要先看站内文档，确认视频通道和任务字段是否与官方一致。

操作	方法与路径	说明
创建任务	POST `/contents/generations/tasks`	返回任务 ID，不返回视频
查询任务	GET `/contents/generations/tasks/{id}`	查询状态与结果
查询列表	GET `/contents/generations/tasks`	批量对账与补偿
取消任务	按文档的取消或删除接口	通常只对排队中的任务有效

不同平台对取消、删除和列表查询的支持程度不同，接入前以文档为准。Base URL 末尾不要重复拼接 /api/v3，否则会出现路径错误。

二、提交任务：一次 POST 要带什么

下面是一个常见的任务创建请求，字段仅作示例：

export ARK_API_KEY="your-api-key"
export BASE_URL="https://ark.cn-beijing.volces.com/api/v3"

curl -sS -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-1-0-pro-250528",
    "content": [
      {"type": "text", "text": "清晨的港口，集装箱吊装，航拍缓慢环绕，写实风格"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}, "role": "first_frame"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false,
    "callback_url": "https://api.example.com/callbacks/seedance"
  }'

几个字段值得注意：

content 是数组，文本、首帧图、参考图、参考视频分别用不同的 type 和 role。
duration、ratio、resolution 的可选范围随模型版本变化，不要直接照搬别家文档。
watermark 影响成片是否带水印，商用前确认平台规则。
callback_url 用于接收任务完成通知，是否支持以实际平台为准。
seed、camera_fixed、return_last_frame 等字段并非所有模型都支持。

提交成功后，把响应里的任务 ID 立刻落库，并与业务单号绑定。后续轮询、重试、对账和费用归集都依赖这个 ID。

三、轮询：状态机与退避策略

查询任务只需要任务 ID：

curl -sS "$BASE_URL/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $ARK_API_KEY"

常见状态与处理方式如下：

status	含义	处理建议
`queued`	排队中	继续等待，必要时取消
`running`	生成中	继续轮询，不要重复提交
`succeeded`	成功	读取结果并立即转存
`failed`	失败	记录错误码，判断是否可重试
`expired`	超时终止	调整超时或参数后重提
`cancelled`	已取消	确认是否为业务主动取消

轮询不要固定一秒一次。建议从 5 秒起步，按 10 秒、20 秒逐步退避，上限 30 秒左右，并加入少量随机抖动，避免多实例同时打到上游。总超时按业务设置，例如 10 分钟；超时后标记为待核对，而不是无限等待。

任务记录通常只能查询一段时间，官方文档给出的口径约为 7 天。超过期限后，历史状态只能依赖自己的任务表，所以状态变更要及时落库。

四、下载与转存结果

任务成功后，响应里会有视频地址。这个地址通常有时效，官方文档给出的有效期约为 24 小时，且部分模型对下载次数有限制。不要把它当成长期 CDN 地址直接交给前端或客户。

正确的做法是：收到成功状态后立即下载，转存到自己的对象存储，并记录任务 ID、业务单号、对象路径、文件大小和校验值。转存完成后再把内部地址写入业务库。这样即使上游链接过期，历史订单仍可回放和交付。

下载环节还要考虑大文件、断点续传、并发上限和失败重试。如果响应里同时返回首帧图或音频，按字段分别转存，不要只保存视频。

五、Webhook 还是轮询

两种方式都能拿到结果，区别在实时性和运维成本：

方式	优点	缺点	适用场景
Webhook	延迟低，减少无效查询	需要公网可达、验签、防重放	生产异步任务
轮询	实现简单，无公网要求	有延迟，产生额外请求	内部工具、测试、兜底
混合	回调为主，轮询兜底	需要状态去重	大多数生产系统

生产环境更稳妥的是“回调加对账”：回调负责低延迟，定时任务扫描长时间未到终态的记录负责兜底。回调接口必须验签、做幂等处理，不能收到一次就重复入库或重复触发下游。回调丢失并不罕见，不能把它当成唯一通知手段。

六、幂等与重复提交

视频任务单价高、耗时长，重复提交的代价比文本接口大得多。建议从四个层面控制：

提交前生成业务幂等键，例如订单号加版本号，先查库再提交。
把任务 ID 与业务单号做唯一索引，数据库层面阻止重复记录。
请求超时不等于任务失败。先按幂等键查库，或查询任务列表，确认没有创建再重试。
只对 429、5xx 和网络错误重试；400 参数错误和内容审核拒绝不要盲目重试。

取消和重提也要记录原因。否则同一个业务单可能产出多条视频，既增加费用，也让对账变得困难。建议每天跑一次对账任务，核对任务状态、费用与产物是否一致。

七、常见错误与排查

401 AuthenticationError：Key 缺失、失效，或请求头格式不对，也可能是 Base URL 与 Key 不匹配。
403 AccessDenied、AccountOverdueError：权限不足、账号欠费或服务未开通。
404 ModelNotOpen、UnsupportedModel：模型未开通或名称拼写错误。
400 SensitiveContentDetected：提示词或素材触发内容审核，应更换素材，而不是反复重试。
400 InvalidParameter：字段名、时长、比例或分辨率不在允许范围内。
429 RateLimitExceeded：降低并发并指数退避，必要时申请更高配额。
failed 或 expired：读取 error.code 和 error.message，区分参数问题、审核拒绝与上游故障。

错误码字符串可能随平台更新，排查时以实际响应和错误码文档为准。把原始错误码、请求 ID 和脱敏后的请求参数一起记入日志，能显著缩短定位时间。

八、迁移检查清单

从官方接口迁到网关，或从一个网关迁到另一个平台，按下面清单逐项确认：

Base URL 和鉴权方式是否整套替换，而不是只换 Key。
model 填 Model ID 还是 Endpoint ID，是否与当前鉴权方式匹配。
请求字段名、时长、比例、分辨率是否在新通道的支持范围内。
状态枚举是否覆盖排队、运行、成功、失败、超时和取消。
结果链接的有效期、下载次数限制和转存逻辑是否验证。
回调地址是否公网可达，是否完成验签与幂等处理。
幂等键、任务表、对账任务和告警是否已经上线。
限流、超时、重试和并发上限是否做过压测。

迁移后先跑小批量任务，对比成功率、平均耗时和单条成本，再逐步放量。不要在没有对账机制的情况下直接切全量。

常见问题

Seedance API 是同步返回视频吗？

通常不是。创建任务只返回任务 ID，需要轮询或等待回调，成功后再下载视频。按同步接口设计容易超时，也容易重复提交。

任务 ID 和结果能保存多久？

按官方文档，任务记录通常可查询约 7 天，结果视频链接的有效期约为 24 小时。长期保存需要自行转存到对象存储。

轮询间隔设多少合适？

可以从 5 秒起步，逐步退避到 15 到 30 秒，并设置总超时。固定高频轮询既浪费请求，也更容易触发限流。

支持 Webhook 回调吗？

官方创建任务接口提供 callback_url 字段，但能否送达受网络和平台策略影响。网关是否支持回调要以站内文档为准，生产环境建议保留轮询兜底。

任务失败会扣费吗？

不同平台和失败类型的规则不同。接入前确认审核拒绝、超时、取消分别如何计费，并用小批量任务核对账单。

下一步

先用最短时长和较低分辨率跑通一条任务，再补齐任务表、轮询、转存和对账。需要统一入口，可以在中商起航 AI 网关注册，并在模型价格页确认 Seedance 通道与计费方式。