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

> Seedance 2.5 产品已经发布，但第一方 ModelArk 模型 ID 仍需等待官方目录确认；本文给出不猜 ID 的接入方法和可运行代码。

- URL: https://blog.laozhang.ai/zh/posts/seedance-2-api
- Published: 2026-02-22
- Updated: 2026-08-04
- Author: LaoZhang AI Team (https://blog.laozhang.ai/zh/about)
- Topic: AI 视频生成
- Tags: Seedance 2.5, Seedance API, 模型 ID, Python, Node.js, BytePlus ModelArk

---
截至 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 目录与第三方 provider 路线的状态关系](https://blog.laozhang.ai/posts/zh/seedance-2-api/img/model-id-check.webp)

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

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

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

| 你看到的入口 | 现在能确认什么 | 接入动作 |
|---|---|---|
| ByteDance Seed 2.5 产品页 | 模型名称与创作能力 | 用于了解能力，不能直接复制 API 参数 |
| BytePlus / 火山方舟官方模型目录 | host、Key scope、已开放模型与异步任务合同 | 只有账号或文档实际列出 2.5 ID 时才启用 |
| 第三方 2.5 API 页面 | 该 provider 可能提供自己的 alias 与 endpoint | 只在同一 provider 内整套使用，不移植到官方 host |

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

当前可核验的 Seedance 2.0 fallback route tuple 如下。请整行选择，不要拆开复制：

| 路线 | Base URL 与 Key 范围 | 模型 ID 命名空间 | 创建、查询与下载合同 |
|---|---|---|---|
| 中国区火山方舟直连 | `https://ark.cn-beijing.volces.com/api/v3`；中国区方舟账号的 Bearer Key | `doubao-seedance-2-0-260128`、`doubao-seedance-2-0-fast-260128`；Mini 精确后缀以账号当前模型列表为准 | `POST /contents/generations/tasks`；`GET /contents/generations/tasks/{id}`；成功后读取任务输出 |
| BytePlus 国际区直连 | `https://ark.ap-southeast.bytepluses.com/api/v3`；正确 resource project 中创建的 ModelArk Key | `dreamina-seedance-2-0-260128`、`dreamina-seedance-2-0-fast-260128`、`dreamina-seedance-2-0-mini-260615` | 同样的创建/查询路径；成功任务返回 `content.video_url` |
| laozhang.ai 网关 | `https://api.laozhang.ai/seedance/api/v3`；Token 必须分配到 `SeeDance2` 分组 | `doubao-seedance-2-0-260128` 或 `doubao-seedance-2-0-fast-260128` | Ark 形状的创建/查询；兼容下载地址为 `https://api.laozhang.ai/v1/videos/{id}/content` |

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


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

需要中国区基础设施、方舟账号归属和 `doubao-*` 合同时，使用[火山方舟创建视频任务官方参考](https://api.volcengine.com/api-docs/view?action=CreateContentsGenerationsTasks&serviceCode=ark&version=2024-01-01)，并在[火山方舟文档中心](https://www.volcengine.com/docs/82379/1520757)复核当前模型和字段。公开示例可能仍出现旧版 Seedance ID，所以部署时应以账号里实际可见的模型列表为准，不能猜 Mini 后缀。

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

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

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

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

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

| 探针 | 观察结果 | 可以得出的结论 |
|---|---|---|
| BytePlus AP 创建地址 | HTTP 401 JSON | 请求到达鉴权边界；不能证明模型已开通或能生成 |
| 火山方舟中国区创建地址 | HTTP 401 JSON | 中国区路径存在且需要鉴权；账号与模型未测试 |
| laozhang.ai 正确 `/seedance/api/v3/...` | HTTP 401 JSON | relay 等待正确 Token；不能证明默认分组 Token 可用 |
| laozhang.ai 少了 `/seedance` 的 `/api/v3/...` | HTTP 404 JSON | 路径错误 |
| 旧 `/seedance/v3/...` | HTTP 200 HTML | 返回网页，不是 API 成功 |

健康检查必须同时判断状态码和 `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));
}
```

![Python 与 Node.js 共用的 Seedance 异步创建、保存 task ID、轮询和结果转存流程](https://blog.laozhang.ai/posts/zh/seedance-2-api/img/async-code-flow.webp)

## 中国区最小 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"
```

| 状态 | 应用含义 | 下一步 |
|---|---|---|
| `queued` | 已接受，仍在队列 | 等回调或稍后查询，禁止创建替代任务 |
| `running` | 正在生成 | 继续持有同一个 task ID |
| `succeeded` | 输出就绪 | 原子更新成功状态并转存视频 |
| `failed` | 上游以错误终止 | 保存错误，分类后再让用户决定是否新建 |
| `expired` | 超过执行窗口 | 记录终态，不自动重复生成 |

把 `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 就继续查询；是否接受仍未知时，显示“提交状态未知”，交给用户或运维确认，不要静默再买一次生成。

| 操作 | 重试规则 |
|---|---|
| 请求尚未离开进程 | 可以首次提交 |
| 创建超时、是否接受未知 | 停止并对账现有 job |
| 已有 task ID 的查询 | 网络/5xx 可有限退避 |
| callback 处理 | 依靠幂等状态迁移重复执行 |
| 成功视频转存 | 可重试复制，不可重新生成 |
| provider 返回 failed | 先区分参数、审核、账号、配额或临时错误 |


## 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 中文页](https://seed.bytedance.com/zh/seedance2_0)确认模型支持文字、图片、音频和视频输入；具体字段和限制必须回到所选 API 路线的当前文档。Ark 合同把素材放在 `content` 中。首帧/尾帧模式和多模态参考不要混写；音频不能单独提交，至少还要有图片或视频。


API 跑通后再用[提示词指南](https://blog.laozhang.ai/zh/posts/seedance-2-prompt-guide)优化生成；需要选供应商时进入[服务商对比](https://blog.laozhang.ai/zh/posts/seedance-2-api-providers-comparison)，不要让当前 implementation owner 变成比价页。

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

## 参考来源

本文引用的外部页面，按正文出现顺序排列。最后更新于 2026-08-04。

- [Seedance 2.5 官方产品页](https://seed.bytedance.com/zh/seedance2_5) (seed.bytedance.com)
- [BytePlus 创建视频任务参考](https://docs.byteplus.com/en/docs/ModelArk/1520757) (docs.byteplus.com)
- [BytePlus 当前模型与价格表](https://docs.byteplus.com/docs/ModelArk/1099320) (docs.byteplus.com)
- [火山方舟创建视频任务官方参考](https://api.volcengine.com/api-docs/view?action=CreateContentsGenerationsTasks&serviceCode=ark&version=2024-01-01) (api.volcengine.com)
- [火山方舟文档中心](https://www.volcengine.com/docs/82379/1520757) (volcengine.com)
- [BytePlus ModelArk API reference](https://docs.byteplus.com/en/docs/modelark/1520757) (docs.byteplus.com)
- [Seedance 2 教程](https://docs.byteplus.com/en/docs/ModelArk/2291680) (docs.byteplus.com)
- [API Key 管理文档](https://docs.byteplus.com/en/docs/ModelArk/1361424) (docs.byteplus.com)
- [ByteDance Seed 中文页](https://seed.bytedance.com/zh/seedance2_0) (seed.bytedance.com)