Seedance 是字节跳动旗下的视频生成模型，常见于广告素材、电商短视频和分镜预演。它的 API 与文本模型完全不同：一次请求不会直接返回视频，而是先创建任务，再轮询状态，最后下载结果。接入方如果按 Chat Completions 的思路写代码，通常会在第一步就卡住。

本文按工程落地顺序，讲清鉴权、提交、轮询、参数、测试、成本和合规。接口地址、模型名和计费方式变化较快，一律以官方文档和站内文档为准。

说明：Seedance、豆包、火山引擎等名称是其权利人的商标，本文仅作技术说明。示例中的接口路径和模型名仅用于演示，实际调用前请在官方或站内文档核对。价格以站内价格页为准。

一、Seedance API 适合什么

  • 电商商品展示视频、主图视频；
  • 信息流广告和短视频素材草稿；
  • 分镜、概念片、风格测试；
  • 社交媒体竖屏内容；
  • 游戏、动画的预演片段。

不适合：需要严格事实准确性的新闻素材、未获授权的真人肖像、需要精确品牌规范的法务或医疗内容。视频生成的可控性仍弱于实拍，重要商单建议人工复核后再投放。

二、异步任务的基本流程

读取配置 → 鉴权 → 提交生成任务 → 拿到 task_id
        → 轮询状态（排队/运行/成功/失败）
        → 成功：下载视频或获取临时 URL
        → 失败：读错误码，决定重试或放弃

和文本接口相比，视频任务有三个额外成本：排队时间、失败重试、结果存储。工程上必须把这三项纳入设计，否则上线后会出现“请求超时但任务还在跑、重复提交导致重复扣费”的问题。

三、鉴权与接入准备

  1. 确认通道：先看站内文档是否已开通 Seedance 视频能力，支持哪些模型、时长和分辨率。
  2. 创建 Key：在控制台新建独立 Key，命名为 seedance-test 或 seedance-prod。
  3. 确认模型名：从价格页或文档复制，不要凭记忆拼写版本后缀。
  4. 确认回调方式：有的通道支持 webhook，有的只支持轮询。
  5. 准备素材：首帧图、参考图先转成可公开访问的 URL，或按文档要求上传。
  6. 设预算：给测试 Key 设额度上限，避免调试时跑出大额账单。

鉴权通常是 Authorization: Bearer <API_KEY>，但部分平台使用 AK/SK 签名或临时 Token。以实际文档为准，不要把一个平台的鉴权方式套到另一个平台。

四、提交任务示例

以下为常见的任务式请求形态，路径和字段仅作示例：

export SEEDANCE_API_KEY="你的密钥"
export BASE_URL="https://你的网关或官方地址"

curl -X POST "$BASE_URL/contents/generations/tasks" \
  -H "Authorization: Bearer $SEEDANCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-video",
    "content": [
      {"type": "text", "text": "雨后的上海街道，镜头缓慢推进，电影感，16:9"},
      {"type": "image_url", "image_url": {"url": "https://example.com/first-frame.jpg"}}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p",
    "watermark": false
  }'

提交成功后，响应里会有任务 ID。把它落库，和业务单号绑定，后续轮询、重试和对账都靠它。

五、轮询与下载

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

常见状态包括排队、运行中、成功、失败。建议：

  • 轮询间隔从 5 秒起步，逐步退避到 15–30 秒；
  • 设置总超时，例如 10 分钟，超时后标记失败而不是无限等；
  • 成功响应里的视频 URL 通常有有效期，及时转存到自己的对象存储；
  • 失败任务记录错误码和请求参数，方便复盘。

六、关键参数

参数 作用 实践建议
prompt / text 描述画面、动作、镜头、风格 先写主体，再写镜头和光线
首帧图 控制起始画面 用清晰、无版权争议的图
duration 视频时长 先用最短档测试
resolution 分辨率 测试用低档，成片再升
ratio 画幅比例 竖屏投放选 9:16
seed 随机种子 固定种子便于对比参数
watermark 是否带水印 商用前确认平台规则

参数名在不同平台可能不同，例如有的叫 image，有的叫 image_url，有的把时长写成字符串。以文档为准，不要直接复制别家的请求体。

七、上线前测试清单

  1. 鉴权是否通过，401 是否能被捕获。
  2. 最短时长、最低分辨率任务能否成功。
  3. 任务 ID 是否稳定返回，能否按 ID 查询。
  4. 轮询超时和最大重试次数是否设置。
  5. 失败原因是否可读，是否区分审核拒绝和系统错误。
  6. 结果 URL 的有效期和转存逻辑是否验证。
  7. 计费是否与预期一致，失败任务是否计费。
  8. 并发提交时是否触发限流。

八、成本怎么估

视频成本通常远高于文本，估算时不要只看单价：

单条成本 =
  单价 × 时长 × 分辨率系数
+ 失败重试成本
+ 存储与带宽
+ 人工审核时间

计费口径可能是按生成秒数、按分辨率档位，或按视频 token 折算。具体单价以站内模型价格为准。建议先跑 20–50 条小批量，统计成功率、平均耗时和单条成本，再决定是否扩量。

九、内容审核与版权风险

  • 肖像权：上传真人照片或生成可识别人物，需要取得授权。
  • 著作权：参考图、风格、音乐、商标都可能涉及第三方权利。
  • 内容政策：暴力、色情、违法、虚假信息会被拒绝或下架。
  • 虚假宣传：广告素材不要生成与实际商品不符的效果。
  • 数据安全：上传的图片和视频可能含客户信息，注意脱敏和留存期限。
  • 商用范围：生成内容能否商用，取决于平台条款和你的素材授权。

建议建立三道关：提交前审查素材，生成后人工抽检，投放前由品牌或法务确认。审核拒绝不是技术故障，不要用换关键词的方式反复绕过。

十、稳定性建议

  • 任务表落库，记录提交时间、状态、耗时和费用；
  • 提交与轮询分离，避免一个请求里同步等待几分钟；
  • 对 429 和 5xx 做指数退避，对 4xx 参数错误不要盲目重试；
  • 准备备用通道或备用模型，视频通道高峰期可能排队；
  • 监控成功率、P95 耗时和单条成本，按天对账。

常见问题

Seedance API 是同步返回视频吗？

通常不是。视频生成多为异步任务，需要提交后轮询或等待回调，再下载结果。

国内可以直接调用吗？

取决于通道、账号和合规条件。使用前确认服务条款、内容政策和当地法规。

生成一条视频要多久？

受排队、时长、分辨率和上游负载影响，从几十秒到几分钟都常见。生产环境要设置超时和重试。

失败会扣费吗？

不同平台规则不同。接入前确认失败、审核拒绝、超时取消分别如何计费。

可以用自己的图片做首帧吗？

多数视频模型支持，但需要图片可被平台访问，且你拥有相应授权。具体字段以文档为准。

下一步

先确认站内是否已开通 Seedance 通道，再用最低配置跑一条任务。需要统一入口，可以在中商起航 AI 网关创建 Key，并在模型价格页核对可用模型。

相关阅读：