Seedance 2 API 文档：API Key、调用、回调与模型 ID

Seedance 2 API 是异步任务接口：POST 只创建任务并返回 ID，GET 查询状态，callback_url 接收状态变化，succeeded 后才取得视频。最常见的接入错误不是提示词，而是把一条路线的 API Key、Base URL 或模型 ID 放进另一条路线。

2026 年 7 月 18 日核验到的三套 route tuple 如下。请整行选择，不要拆开复制：

dreamina-* 不能放到中国区或网关域名；doubao-* 也不能直接替代 BytePlus ID。正确的“Seedance 2 API 文档”必须同时说明域名、Key scope、模型 namespace 和 create/query/download 合同。

先根据账号与控制权选路线

需要中国区基础设施、方舟账号归属和 doubao-* 合同时，使用火山方舟创建视频任务官方参考，并在火山方舟文档中心复核当前模型和字段。公开示例可能仍出现旧版 Seedance ID，所以部署时应以账号里实际可见的模型列表为准，不能猜 Mini 后缀。

需要国际区官方账号、Standard/Fast/Mini 三档或 endpoint 级控制时，使用 BytePlus ModelArk API reference。当前 Seedance 2 教程列出三条 dreamina-* ID；API Key 管理文档说明 Key 隶属于 resource project，还可限制模型、自定义 endpoint 和 IP。

如果团队更看重统一开发者网关，可按 laozhang.ai Seedance 文档使用已核验的 relay 路径。它适合当前文档覆盖的 Standard/Fast 异步调用；如果需要官方账号控制、BytePlus Mini、未暴露的区域或能力，就停止使用网关并切回官方直连。当前网关文档不支持真人人脸工作流，相关素材先看真人输入边界。

这里不比较价格，也不承诺可用性。真正能否调用仍取决于账号区域、模型开通、Key 权限和余额。

用响应状态和 Content-Type 先排除错路径

本轮对公开创建路径执行了无 Key、空 JSON 的 POST {} 探针，没有创建任何生成任务：

健康检查必须同时判断状态码和 Content-Type。401 application/json 只能证明到达鉴权层；200 text/html 应直接判错。本文没有执行带 Key 的生成，也不声称已经生成视频。

创建并保护 API Key

官方直连时，在目标项目和区域内创建 Key。不要把另一个 project 或区域的激活状态当成当前域名可用。Key 只放服务端环境变量，不写进网页 JavaScript、客户端安装包、Git 仓库或 callback URL。

bash
export ARK_API_KEY="仅放服务端"
export SEEDANCE_BASE_URL="https://ark.cn-beijing.volces.com/api/v3"
export SEEDANCE_MODEL="doubao-seedance-2-0-260128"

启动时把三项作为一个配置对象校验：

ts
function assertRoute(baseUrl: string, model: string, key: string) {
  if (!key) throw new Error("缺少服务端 API Key");

  const bytePlus = baseUrl.includes("bytepluses.com");
  const china = baseUrl.includes("volces.com");
  const relay = baseUrl.includes("api.laozhang.ai/seedance/api/v3");

  if (bytePlus && !model.startsWith("dreamina-seedance-")) {
    throw new Error("BytePlus 必须使用 dreamina-* 模型 ID");
  }
  if ((china || relay) && !model.startsWith("doubao-seedance-")) {
    throw new Error("当前路线必须使用 doubao-* 模型 ID");
  }
}

这个 guard 只能防止 route/model mismatch，不能代替真实鉴权与模型开通检查。

中国区最小 API 调用

下面示例只适用于中国区火山方舟 Standard。创建接口返回 task ID，不会同步返回视频：

bash
curl -X POST \
  "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks" \
  -H "Authorization: Bearer $ARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "content": [{
      "type": "text",
      "text": "安静的桌面产品镜头，缓慢推进，自然环境声"
    }],
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": true,
    "callback_url": "https://api.example.com/webhooks/seedance"
  }'

提交前或提交过程中，先在本地写入 job 和规范化 request hash；收到响应后立刻保存 provider task ID。job 至少绑定 route、model、用户、提示词/素材指纹和输出参数。

查询时必须继续使用同一套 Base URL 与 Key：

bash
curl \
  "https://ark.cn-beijing.volces.com/api/v3/contents/generations/tasks/$TASK_ID" \
  -H "Authorization: Bearer $ARK_API_KEY"

把 content.video_url 当作交付地址，不要当产品永久地址。成功后尽快复制到自己的对象存储；复制失败可以重试，但不能重新生成视频。

callback 与轮询要写回同一个 job

callback_url 是可选字段。BytePlus 当前官方合同说明，状态变化时 POST 的 payload 与查询任务响应同形；succeeded 或 failed 通知若 5 秒内没有成功确认，会重试 3 次。这一“5 秒 / 3 次”是 BytePlus 合同，不应自动套用到火山方舟中国区或网关；部署其他路线时重新核对该路线当前的 callback 约定。

因此 callback handler 必须幂等：按 provider task ID 找到本地 job；校验它属于预期 route 和业务用户；相同状态重复到达直接忽略；终态不得回退到 running；成功后只入队一次“转存输出”任务。再为超过 callback 等待时间且仍非终态的 job 运行轮询修复器，调用 GET .../tasks/{id}，复用同一状态迁移函数。

当前公开参考没有给出可以安全写成通用事实的 webhook 签名方案，本文不虚构签名字段。实现层应强制 HTTPS、限制 payload 大小和 Content-Type、校验 task ownership，并在提交状态变更后快速响应。

ts
const terminal = new Set(["succeeded", "failed", "expired"]);

async function applyState(event) {
  const job = await jobs.findByProviderTaskId(event.id);
  if (!job) throw new Error("未知 provider task");

  await jobs.transaction(async (tx) => {
    const current = await tx.forUpdate(job.id);
    if (current.providerStatus === event.status) return;
    if (terminal.has(current.providerStatus)) return;
    await tx.update(job.id, { providerStatus: event.status });
    if (event.status === "succeeded") await tx.enqueueOutputCopy(job.id);
  });
}

创建超时必须触发 duplicate-create stop rule

最危险的情况是：上游已经接受创建请求，但客户端在拿到 task ID 前超时。

**停止规则：**只要本地 job 可能已经到达 provider，就不能因为 HTTP 超时再发第二个 POST。先按 request hash、provider ID、请求日志和 callback 做对账；已有 ID 就继续查询；是否接受仍未知时，显示“提交状态未知”，交给用户或运维确认，不要静默再买一次生成。

Standard、Fast、Mini 与 priority 的边界

BytePlus 当前三条模型 ID 是 dreamina-seedance-2-0-260128、dreamina-seedance-2-0-fast-260128、dreamina-seedance-2-0-mini-260615，分别对应质量优先、速度/成本平衡和成本性能路线。它们只属于 BytePlus，不能替代中国区或网关的 doubao-* ID。

BytePlus 创建接口还为 Seedance 2 记录了 priority 0–9。更大值只会在同一 endpoint 内让 queued 任务排在较低值之前，不会打断 running 任务、跨 endpoint 排队，也不是“生成加速”开关；离线 flex 推理不适用。

参考素材与上线边界

ByteDance Seed 中文页确认模型支持文字、图片、音频和视频输入；具体字段和限制必须回到所选 API 路线的当前文档。Ark 合同把素材放在 content 中。首帧/尾帧模式和多模态参考不要混写；音频不能单独提交，至少还要有图片或视频。

API 跑通后再用提示词指南优化生成；需要选供应商时进入服务商对比，不要让当前 implementation owner 变成比价页。

上线前最后确认：Key 只在服务端；route tuple 整体版本化；task ID 先保存再轮询；callback 幂等且轮询可修复；priority 不被误写成速度保证；创建超时不会自动产生第二个任务；健康检查拒绝 HTML；部署前重新核对模型 ID、域名和账号权限。