Seedance 2.5 API 接入指南：模型 ID、Python 与 Node.js

截至 2026 年 8 月 4 日，ByteDance Seed 已公开 Seedance 2.5 产品页，但 BytePlus 当前公开视频 API 与模型定价表仍只列 Seedance 2.0 系列。也就是说，2.5 模型能力已经确认，第一方 ModelArk 2.5 模型 ID 尚未在可核验目录中公开。此时最安全的接入方式不是猜 ID，而是先确认 provider 的完整 route contract，再写 Python 或 Node.js。

先确认 Seedance 2.5 API 到底开放到哪一层

Seedance 2.5 官方产品页确认单段最长 30 秒、两次视频延长、更强的参考与编辑能力，以及白模控制和绿幕编辑。这些是模型产品事实，但该页没有给出 API host、API Key 获取方式、model ID 或请求 schema。

与此同时，BytePlus 创建视频任务参考在 2026 年 7 月 31 日更新后仍把公开视频能力归入 Seedance 2.0 series；BytePlus 当前模型与价格表也只列三条 2.0 ID。因此搜索结果或第三方页面中出现的 dreamina-seedance-2-5-260628，目前不能当作 BytePlus 已公开的官方 ID。

如果当前项目必须今天上线，使用已经列入官方目录的 Seedance 2.0 fallback；如果业务必须是 2.5，就等待官方账号目录出现 2.5，或选择能明确给出 host、模型 ID、请求字段、计费和安全边界的第三方 provider。

当前可核验的 Seedance 2.0 fallback 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，不能代替真实鉴权与模型开通检查。

用 Python 提交一次并轮询同一个任务

下面代码适用于 Ark 形状的异步合同。先在 provider 的正式文档或控制台填写三项环境变量；SEEDANCE_MODEL 可以是当前官方 2.0 fallback，也可以是该 provider 明确发布的 2.5 ID。不要把搜索摘要里的 ID 直接放进生产环境。

python
import os
import time
import requests

base_url = os.environ["SEEDANCE_BASE_URL"].rstrip("/")
api_key = os.environ["SEEDANCE_API_KEY"]
model = os.environ["SEEDANCE_MODEL"]
headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}

payload = {
    "model": model,
    "content": [{"type": "text", "text": "雨后街道上的产品镜头，缓慢推进，自然环境声"}],
    "ratio": "16:9",
    "resolution": "720p",
    "duration": 5,
    "generate_audio": True,
}

created = requests.post(
    f"{base_url}/contents/generations/tasks",
    headers=headers,
    json=payload,
    timeout=30,
)
created.raise_for_status()
task_id = created.json()["id"]  # 立即保存到数据库

while True:
    task = requests.get(
        f"{base_url}/contents/generations/tasks/{task_id}",
        headers=headers,
        timeout=30,
    )
    task.raise_for_status()
    data = task.json()
    if data["status"] in {"succeeded", "failed", "expired"}:
        print(data)
        break
    time.sleep(5)

POST 超时且没有拿到 task ID 时，不要自动再发一次。上游可能已经接受任务；应把本地 job 标记为“提交结果未知”，先用 callback、请求日志或 provider 支持渠道对账。

用 Node.js 复用同一个异步合同

Node.js 18 及以上版本可直接使用 fetch。代码仍从服务端环境变量读取 route，不把 Key 放进浏览器或移动端。

js
const baseUrl = process.env.SEEDANCE_BASE_URL.replace(/\/$/, "");
const apiKey = process.env.SEEDANCE_API_KEY;
const model = process.env.SEEDANCE_MODEL;

const request = async (path, init = {}) => {
  const response = await fetch(`${baseUrl}${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Content-Type": "application/json",
      ...init.headers,
    },
  });
  const type = response.headers.get("content-type") || "";
  if (!type.includes("application/json")) throw new Error(`预期 JSON，实际为 ${type}`);
  const data = await response.json();
  if (!response.ok) throw new Error(`${response.status}: ${JSON.stringify(data)}`);
  return data;
};

const created = await request("/contents/generations/tasks", {
  method: "POST",
  body: JSON.stringify({
    model,
    content: [{ type: "text", text: "A ceramic cup turns slowly on a clean studio table" }],
    ratio: "16:9",
    resolution: "720p",
    duration: 5,
    generate_audio: true,
  }),
});

const taskId = created.id; // 在继续前持久化
for (;;) {
  const task = await request(`/contents/generations/tasks/${taskId}`);
  if (["succeeded", "failed", "expired"].includes(task.status)) {
    console.log(task);
    break;
  }
  await new Promise((resolve) => setTimeout(resolve, 5000));
}

中国区最小 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 == null) 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、域名和账号权限。