豆包 Seedance 2.0 视频生成 API 指南：火山引擎 Ark 异步任务接入

豆包 Seedance 2.0 是字节跳动的视频生成模型系列。它的 API 形态本质上是异步任务：先创建生成任务，保存返回的 task id，轮询到成功状态，然后在结果 URL 过期前取回视频。如果使用 TheRouter，稳妥的接入方式是通过已验证的 Seedance 模型 ID 路由媒体生成任务，同时把 provider 特有的任务字段保留为显式、可测试的参数。

我们写这篇指南，是因为 Seedance 相关搜索已经非常工程化：开发者不是在问模型是否存在，而是在问调用哪个 endpoint、传哪个 model id、轮询逻辑放在哪里。短答案是：最终渲染用 doubao/doubao-seedance-2-0，提示词迭代用 doubao/doubao-seedance-2-0-fast，每一次请求都要围绕可重试的异步工作流来设计。

1. 替换三个值，不是三个 SDK。在现有 OpenAI 客户端里改 api_key、base_url、model。请求与响应代码保持不变。
2. 显式映射 model ID。目标供应商的 model id 几乎不会和 OpenAI 完全一致。 在业务代码之外维护一份 { openai_id: target_id } 映射。
3. 验证流式格式。SSE 分片必须遵循 OpenAI 的 data: {...} + data: [DONE] 契约。切生产前先跑一次流式调用。
4. 检查限流响应头。部分供应商不返回 x-ratelimit-*。 在包装层 做缺省兜底，缺头不要崩。
5. 留回滚路径。用 feature flag 切流；新旧 endpoint 影子并行 24 小时，再正式切换。

Seedance 2.0 速览

ByteDance Seed 页面把 Seedance 2.0 描述为统一的多模态音视频联合生成架构，可使用文本、图片、音频和视频作为参考。火山方舟文档中也有独立的视频生成 API 目录，包含创建、查询、列表、取消和删除任务页面；创建任务页面最近更新于 2026-06-25。来源：ByteDance Seedance 2.0、火山方舟创建视频生成任务 API、火山方舟 Seedance 2.0 系列教程。检索时间：2026-06-26。

Standard 和 Fast 怎么选

当视频已经接近生产用途时，选择 Seedance 2.0 标准版：产品主视觉、最终社媒素材、品牌审核，或者任何“运动稳定性比速度更重要”的提示词。TheRouter 模型页把它描述为旗舰级 text/image-to-video 模型，模型 ID 是 doubao/doubao-seedance-2-0。

当提示词还在变化时，选择 Seedance 2.0 Fast。我们更倾向于把它用于分镜草稿、镜头语言调整，以及在投入最终渲染成本前确认参考图是否合适。Fast 模型页将它定位为更低成本、更低延迟的迭代版本。

建议放在同一份内部文档里的链接：

• Provider 页面：TheRouter 上的 ByteDance / Doubao
• 标准模型：doubao/doubao-seedance-2-0
• Fast 模型：doubao/doubao-seedance-2-0-fast
• 相关 provider 指南：Volcengine Ark / Doubao API Complete Guide
• 相邻视频模型：OpenAI Sora 2 Pro

原生火山方舟任务流程

Volcengine 的 Seedance API 最容易理解为一个队列：

1. 提交任务，带上 model id、content references、duration、ratio、resolution 和 watermark 配置。
2. 保存返回的 task id。
3. 用指数退避轮询任务 endpoint。
4. 只把 succeeded 当作可下载状态。
5. 把生成结果保存到自己的对象存储；第三方教程提到输出 URL 可能过期，不要把 provider URL 当唯一副本。

原生 Ark 风格的文生视频请求如下：

curl -X POST "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [
      {
        "type": "text",
        "text": "A golden retriever running through a sunlit wheat field, wide tracking shot, cinematic lighting"
      }
    ],
    "resolution": "1080p",
    "ratio": "16:9",
    "duration": 5,
    "watermark": false
  }'

原生 Ark 的公开模型 ID（doubao-seedance-2-0-260128）和 TheRouter 的模型 ID（doubao/doubao-seedance-2-0）并不相同。把映射放在配置里，不要把字符串散落在业务代码里。来源：Apidog Seedance 2.0 API walkthrough，检索时间：2026-06-26；并与本地 TheRouter model data 交叉核对。

通过 TheRouter 路由 Seedance

对 TheRouter 来说，接入目标不是隐藏“视频生成是异步任务”这一事实，而是在保留 provider 任务语义的同时，提供统一账号、统一路由层和稳定的模型标识。

一个最小 TypeScript 形态如下：

const response = await fetch("https://api.therouter.ai/v1/videos", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.THEROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "doubao/doubao-seedance-2-0",
    prompt: "A clean product demo shot, white background, slow orbit camera",
    seconds: 5,
    aspect_ratio: "16:9",
    size: "1080p",
  }),
});

const task = await response.json();
console.log(task.id);

然后轮询返回的 id：

async function waitForVideo(taskId: string) {
  for (let attempt = 0; attempt < 30; attempt++) {
    const r = await fetch(`https://api.therouter.ai/v1/videos/${taskId}`, {
      headers: { Authorization: `Bearer ${process.env.THEROUTER_API_KEY}` },
    });
    const task = await r.json();
    if (task.status === "succeeded") return task;
    if (task.status === "failed" || task.status === "expired") throw new Error(task.status);
    await new Promise((resolve) => setTimeout(resolve, Math.min(30000, 2000 * 2 ** attempt)));
  }
  throw new Error("Seedance task timed out");
}

这个例子刻意保持保守：上线前请确认你账号当前的媒体 endpoint 和响应字段。我们能负责表达的能力是：TheRouter 在已实现路径上支持路由媒体生成任务；除非文档或代码已经验证，否则不应声称每一个 provider 特有字段都被标准化。

文生视频和图生视频示例

先从文生视频开始，因为它能隔离最核心的变量：

{
  "model": "doubao/doubao-seedance-2-0",
  "prompt": "A macro shot of a mechanical keyboard assembling itself, shallow depth of field, soft studio lighting",
  "seconds": 5,
  "aspect_ratio": "16:9",
  "size": "1080p"
}

轮询跑通后，再增加参考图：

{
  "model": "doubao/doubao-seedance-2-0-fast",
  "prompt": "Animate the reference image into a slow dolly-in product reveal, keep the logo stable",
  "image_url": "https://example.com/reference-product.png",
  "seconds": 5,
  "aspect_ratio": "1:1",
  "size": "720p"
}

我们的生产建议是保存原始 prompt、参考素材 hash、model id、task id、最终 asset URL，以及 provider 返回的错误体。视频问题很难复现，只保存最终 URL 通常不够。

价格、延迟和结果保留

TheRouter 本地 model data 目前把 Ark 视频成本镜像为按视频请求估算：doubao/doubao-seedance-2-0 为 4.66668，doubao/doubao-seedance-2-0-fast 为 3.66672，并标注需要根据真实使用继续修正。火山引擎价格页更新于 2026-06-23，搜索摘要显示视频价格会随分辨率、宽高比、输入时长和输出时长变化。

因此更负责任的工程策略是：

• 不承诺 Seedance 是最便宜的视频生成路线；
• 在产品 UI 中限制 duration 和 resolution；
• 把请求参数和成本记录放在一起；
• 用 Fast 做 prompt 探索，再用标准版做最终渲染；
• 成功后立即下载并重新托管视频，不依赖 provider 的临时存储。

来源：火山方舟模型价格、本地 docs/lib/models-data.ts、Apidog Seedance API walkthrough。检索时间：2026-06-26。

常见错误与修复

生产检查清单

• 把模型 ID 放进配置：doubao/doubao-seedance-2-0 和 doubao/doubao-seedance-2-0-fast。
• 对任务提交实现 idempotency，避免重试创建重复视频。
• 使用指数退避轮询，并设置上限超时。
• 保存 prompt、model、parameters、task id、状态历史、成本估算和最终 asset URL。
• 把完成的视频下载到持久化存储。
• 把 Fast 和标准版作为产品选择暴露出来，不要隐藏质量权衡。
• 在内部文档中链接 TheRouter ByteDance provider 页面 和两个 Seedance 模型页，方便运营核对当前元数据。

FAQ

Seedance 2.0 是 OpenAI-compatible 吗？

原生 Volcengine 任务 API 不是一个简单的 chat completions 调用；它是视频任务 API。TheRouter 可以在已实现的媒体生成路径上作为路由层，但你仍然应该把视频生成视为异步任务，而不是阻塞式 OpenAI chat response。

在 TheRouter 上应该使用哪个 model id？

标准质量使用 doubao/doubao-seedance-2-0，更快迭代使用 doubao/doubao-seedance-2-0-fast。原生 Ark ID 则包含类似 doubao-seedance-2-0-260128 的日期版本。

可以上传图片作为参考吗？

可以。TheRouter 模型元数据把两个 Seedance 2.0 变体都标为 text 和 image 输入、video 输出；ByteDance 也把 Seedance 2.0 描述为支持多模态参考。批量流程上线前，请先验证所选 endpoint 的具体 image 字段格式。

轮询应该等多久？

用产品级超时，不要直接复制某篇文章里的固定秒数。可以从 2-5 秒间隔开始，逐步退避到 30 秒，并在 provider 队列较慢时让用户看到任务仍在处理中。

是否所有视频都应该先走 Fast？

不需要。提示词还不确定时用 Fast；当分镜或参考图已经通过人工确认时用标准版。这个拆分能省成本，也不会隐藏质量取舍。