Seedance 2.5 API 开发者指南：端点、鉴权与视频生成

Seedance 2.5 API 开发者指南：端点、鉴权与视频生成

Seedance 2.5 是一款长时长、多模态的视频模型，因此驱动它的 API 是异步的，而不是单次请求-响应。你需要提交一个生成任务，轮询任务完成状态，再下载结果。理解了这一模式，再加上端点、鉴权请求头，以及时长、分辨率和参考素材等负载字段，剩下的部分就很简单了。

本指南完整梳理了 Seedance 2.5 API 的接入契约：端点、鉴权、请求体、异步轮询，以及可直接运行的 curl 与 Python 示例。文中示例面向 PixMind api-platform 路由，该路由与字节跳动对该模型的契约保持一致。同时附上与 Seedance 2.0、Kling 的 API 模式并排对比，一份端到端生产流水线案例，第三方开发者资源，以及一份覆盖限流、并发、回调与积分校验的扩展 FAQ。所有端点与鉴权细节均于 2026-07-31 对照线上后端核对。

Seedance 2.5 模型总览

Key Takeaways

• 端点： POST /api-platform/v1/generations 创建任务；GET /api-platform/v1/task/{task_id} 轮询结果。
• 鉴权： Authorization: Bearer <API_KEY>（或 X-API-Key 请求头）；在 PixMind 控制台中创建带 video 权限范围的 Key。
• 请求体： { model, prompt, duration, resolution, aspect_ratio, reference_images, reference_videos, generate_audio }。
• 异步执行： 创建调用返回 taskId，轮询直到 status 变为 ready，再读取 videoUrl。
• 跨厂商结构一致： Seedance 2.5、Seedance 2.0 与 Kling 都采用同样的"提交后轮询"模式。差异在于端点路径、参考素材配额和字段名。
• 生产实践： 创建时附带 Idempotency-Key，有限次重试加退避地轮询，提交前校验积分，并在迭代阶段回退到更便宜的路由。
• PixMind 上的 API 访问即将上线（Coming Soon）； 路由已写好文档并就绪，后端连接正在最终调试。

前置准备：获取 API Key

调用 Seedance 2.5 时使用绑定到你账号的 API Key 进行鉴权。请在 PixMind api-platform 控制台中创建并妥善保管，像对待任何密钥一样。代码中通过环境变量读取 Key，不要把它提交到代码仓库：

export PIXMIND_API_KEY="pk-xxxxxxxxxxxxxxxx"

创建 API Key

在 PixMind 上，Key 的权限按工作负载（image / video）划分。调用 Seedance 2.5 之前请确保你的 Key 已开启 video 权限。

开发者提示： 按环境（dev / staging / prod）轮换 Key，并为每个 Key 设置其所需的最小工作负载权限。仅有 video 权限的 staging Key 不会泄漏到 image 流水线中，这样即便 Key 被泄露也能控制影响范围。按固定节奏轮换 Key，并记录最后一次使用的时间戳，便于发现和吊销长期闲置的 Key。

观看：Seedance 2.5 工作流导览

在写代码之前，理解 2.5 升级最快的方式就是观看官方演示素材和社区分析。下面两段导览涵盖了 30 秒原生生成、4K 输出、区域级编辑，以及 API 暴露的 50 路参考素材工作流：

noscript 后备链接：YouTube 上的 Seedance 2.5 演示，涵盖 30 秒原生片段、区域级编辑和 50 路多模态参考素材。

若想更深入地从编辑视角讨论这些工作流升级对生产流水线的意义，"Seedance 2.5 Changes Everything" 这篇分析值得与官方演示一起观看：

noscript 后备链接：YouTube 上的 Seedance 2.5 Changes Everything。

Seedance 2.5 API 契约

端点

创建生成任务：

POST /api-platform/v1/generations

轮询完成状态：

GET /api-platform/v1/task/{task_id}

创建端点是统一的生成入口：它会读取 model 字段并据此分发。传入 model: "seedance-2.5"，路由会处理后续的视频生成流水线。

鉴权

将 API Key 作为 Bearer token 发送（与 OpenAI SDK 兼容）：

Authorization: Bearer $PIXMIND_API_KEY

如果你更喜欢这种形式，鉴权中间件也接受 X-API-Key 请求头。两种都支持，请任选其一并在客户端代码中保持一致，便于追踪日志和重试。

请求体

关于参考素材： Seedance 2.5 单次请求最多接受 50 个多模态输入，图片、视频、文本和音频合并计算。给每个参考素材分配一个明确的角色（身份、形状、动作、配色、节奏），并移除那些在同一属性上相互冲突的素材。

Seedance 2.5 API 与 Seedance 2.0、Kling 的对比

目前主流的视频生成 API 大多采用同样的异步结构：一次 POST 创建任务，一次 GET 轮询直到完成。它们的差异在于端点路径、鉴权约定、参考素材配额，以及负载中的字段名。下表针对开发者规划接入时最常对比的三套 API，列出了这些差异。

第一手观察： 异步结构相同，意味着客户端代码可以在不同厂商之间复用。把"创建+轮询"循环封装进一个 generate_video(model, payload) 函数，只切换模型 ID，就能用同一套代码对 Seedance 2.5、Seedance 2.0 Fast 和 Kling 做 A/B 对比。这是按镜头挑选合适路由而无需重写接入代码的最省钱方式。

实操结论：如果你的团队已经为 Seedance 2.0 搭建过轮询客户端，迁移到 2.5 只需要改模型字符串，再加上新的参考素材和时长字段。无需重新设计接入方式。

Seedance 2.5 与 Kling 模型对比

第一步：创建生成任务

下面是一个最小化的创建请求：一段 5 秒、720p、16:9、带文本提示词的片段。Idempotency-Key 请求头是可选的，但建议在生产环境的任何提交中都带上：

curl -X POST https://aihub-admin.aimix.pro/api-platform/v1/generations \
  -H "Authorization: Bearer $PIXMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "A courier in a yellow jacket cycling through a neon-lit rainy Tokyo street at night, tracking shot, cinematic, no text",
    "duration": 5,
    "resolution": "720p",
    "aspect_ratio": "16:9"
  }'

成功响应会返回任务 ID。这里不会直接拿到视频，而是拿到一个用于轮询的句柄：

{
  "code": 1000,
  "data": {
    "taskId": "47264",
    "type": "video",
    "status": "processing"
  }
}

如果返回 code: 400 且提示 "模型不存在或未配置"，说明该端点上还未启用 seedance-2.5 的后端路由。这正是 PixMind 当前处于 Coming Soon 的状态，后端连接仍在最终调试。

第二步：轮询任务直到 ready

视频生成是异步的。使用第一步拿到的 taskId 轮询任务端点：

curl -X GET https://aihub-admin.aimix.pro/open-api/v1/task/47264 \
  -H "Authorization: Bearer $PIXMIND_API_KEY"

status 字段会依次经过 pending、processing、ready。每 3 到 5 秒轮询一次。任务就绪后，响应中会包含最终的视频 URL：

{
  "code": 1000,
  "data": {
    "taskId": "47264",
    "status": "ready",
    "progress": 100,
    "videoUrl": "https://.../seedance-2-5-47264.mp4",
    "coverUrl": "https://.../seedance-2-5-47264-cover.webp"
  }
}

终态失败包括 failed、error、canceled 和 cancelled。需要处理这些状态，并将 description 字段输出到日志。

开发者提示： 单个任务 3 到 5 秒的轮询间隔没问题，但规模一大就会迅速放大。对于 20 个任务排队的情况，建议使用单一的调度器循环，每轮对每个进行中的任务各轮询一次，并随着任务等待时长加长采用指数退避（5 秒、5 秒、10 秒、15 秒，封顶 30 秒）。这样能在不让请求量失礼的前提下，避免拖长整批任务的 p99 延迟。

第三步：下载并使用结果

status 变为 ready 后，下载 videoUrl（可选地下载 coverUrl 作为封面帧）。文件是标准 MP4，可按你的应用需要进行转码、托管或嵌入。

对于 Web 落地页，常见的做法是把它压缩成 8 至 10 秒、带 fast-start 可自动播放的 H.264 片段，提取一张 WebP 封面图，并把两者都托管到自己的 CDN 上。（PixMind 的 Seedance 2.5 案例素材就托管在 cdn.pixmind.io。）生产环境不要直接热链 API 返回的 videoUrl，因为该 API URL 不保证长期有效。

完整 Python 示例

下面是一段完整、可直接运行的 Python 代码片段：创建任务、轮询直到 ready，并打印视频 URL。它额外加了 Idempotency-Key、有限次重试循环和超时上限，这三样恰恰是生产环境客户端所必需、而 hello-world 示例常常省略的部分：

import time
import uuid
import requests

API_BASE = "https://aihub-admin.aimix.pro"
API_KEY = "your-pixmind-api-key"  # 权限范围：video

GEN = f"{API_BASE}/api-platform/v1/generations"
TASK = f"{API_BASE}/open-api/v1/task"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

# 1. 携带幂等键创建任务，避免重试时启动第二个被计费的重复任务
payload = {
    "model": "seedance-2.5",
    "prompt": "A 30-second continuous hero shot: a character walking through a neon city that flows into a product reveal",
    "duration": 30,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "generate_audio": True,
}
headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
create = requests.post(GEN, headers=headers, json=payload, timeout=30).json()
task_id = create["data"]["taskId"]
print(f"Task created: {task_id}")

# 2. 有限次重试轮询，并采用温和退避
max_attempts, delay = 100, 5
for attempt in range(max_attempts):
    time.sleep(delay)
    t = requests.get(f"{TASK}/{task_id}", headers=HEADERS, timeout=15).json()
    status = t["data"]["status"].lower()
    print(f"attempt={attempt + 1} status={status} progress={t['data'].get('progress', 0)}%")
    if status in ("ready", "succeeded", "completed"):
        print("Video URL:", t["data"]["videoUrl"])
        break
    if status in ("failed", "error", "canceled", "cancelled"):
        raise RuntimeError(f"Task failed: {t['data']}")
    delay = min(delay + 2, 30)  # backoff, capped at 30s
else:
    raise TimeoutError(f"Task {task_id} did not finish in {max_attempts * 5}s")

端到端案例：30 秒产品视频流水线

这是大多数 API 指南会略过的部分：一个真实团队如何把上面的契约串成可复用的生产流水线。场景设定是 D2C 品牌下的一个 4 人创意团队，在固定预算和硬截止日期下为一款新品发布制作 30 秒主形象视频。下面这套流程，就是能稳定按期交付的那种形态。

流水线总览

团队把工作拆成四个阶段：迭代（在 Seedance 2.0 Fast 上做低成本 A/B 测试）、最终生成（一次 1080p / 30 秒的 Seedance 2.5 跑批）、审查与区域修改（针对目标区域的 Seedance 2.5 区域重生成），以及交付（转码、封面图、上传 CDN）。每个阶段都复用同一套客户端代码，只有模型 ID 和负载会变化。正是这种切分让流水线可以跨活动复用。

参考素材分配

在调用任何 API 之前，团队会先给每个参考素材分配一个明确的角色，并记录在共享表格中，保证提示词和负载保持同步。在 50 路输入预算中挑选 5 个，每个各司其职：

提示词里会逐项明确映射："保持 @Image 1 中人物不变；匹配 @Image 2 中的产品；@Video 1 仅用于镜头运动；剪辑点对齐 @Audio 1。" 这套映射就是创意方向与 API 负载之间的契约。没有角色的参考素材就不会进请求。

迭代阶段（成本控制）

在烧钱跑 30 秒的 2.5 之前，团队会先用 Seedance 2.0 Fast 在 5 秒、720p 上验证提示词和参考素材。这仍然是同一个 POST /api-platform/v1/generations 调用，只是把 model 设为 "seedance-2.0-fast"。三次迭代的成本只是单次 2.5 跑批的零头，却能在预算落定之前暴露参考素材之间的冲突。调度器会记录每次迭代的 taskId、状态和耗时秒数，便于创意负责人并排对比不同版本。

第一手观察： 跳过这一步、直接跑 30 秒 2.5 生成的团队，通常要烧掉三到四次全价跑批才能修掉本可以在 Fast 上发现的提示词冲突。迭代阶段是整条流水线 ROI 最高的环节，能稳定按期交付的团队都把它当作强制步骤。

最终生成（Seedance 2.5，30 秒 / 1080p）

Fast 迭代确认提示词读得通顺之后，团队就提交真正的生成：model: "seedance-2.5"、duration: 30、resolution: "1080p"，附上全部 5 个参考素材和完整的角色映射提示词。创建调用带上 Idempotency-Key，这样 CI runner 的网络重试不会启动第二个被计费的任务。调度器在提交最终的 taskId 之前，需要创意负责人先复核最终的提交日志，这是一道只需一分钟的检查，能避免昂贵的提示词笔误。

轮询、错误与幂等

调度器每 5 秒轮询一次任务，逐步退避到 30 秒，最多重试 100 次（约 8 分钟）。只有当失败描述指向后端瞬时问题时，终态失败（failed、error）才会触发一次使用新 Idempotency-Key 的重试。参考素材或提示词错误会直接反馈给创意负责人，先修复再重提，而不是盲目重试。调度器在每次尝试时写一条结构化日志（任务 ID、状态、进度、耗时秒数），便于上线后审计成本和延迟。

区域修改

审查时，客户要求把最后一个镜头右侧货架上的产品换掉。团队提交一个只针对该区域的区域级编辑任务，保留片段其余部分的运动和身份。这是 2.5 在客户项目中最有价值的能力：原来一整天的往返修改，现在变成 10 分钟的重生成。流水线会在项目日志中保持原 taskId 与编辑后 taskId 的关联，让每一帧交付画面都可追溯到来源。

交付

ready 后的 videoUrl 被下载，转码为带 fast-start、可 Web 自动播放的 H.264，再配上从 coverUrl 提取的 WebP 封面图，并上传到团队自己的 CDN。最终素材推送到落地页，发布前逐帧复核（身份、手部、产品几何、Logo、音画同步）。

成本管控

这条流水线在三处封顶支出。第一，迭代跑在 Fast 上而不是 2.5。第二，每次提交 2.5 之前先做积分预检，如果钱包余额低于所选时长和分辨率的阈值就直接中止。第三，调度器里设有每次活动硬性的任务预算上限，一旦达到就拒绝提交新任务。Seedance 2.5 的定价尚未公布，因此团队把任何按秒计价的数字都当作估算值，并在每次活动前读取实时生成器查看当前积分。

处理 50 路多模态参考素材

50 路多模态输入这一主打能力，在负载中以公开 URL 数组的形式出现：

{
  "model": "seedance-2.5",
  "prompt": "Keep the character from the first image unchanged; use the video for body motion and the audio for rhythm",
  "duration": 20,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "reference_images": ["https://cdn.example.com/character.jpg", "https://cdn.example.com/product.jpg"],
  "reference_videos": ["https://cdn.example.com/motion.mp4"],
  "generate_audio": true
}

所有参考素材 URL 必须可公开访问。给每个素材分配一个角色，并在提示词中说明（例如 "仅将 @Video 1 用于身体动作"），让模型清楚哪个输入控制哪个属性。

开发者提示： 在提交之前，先校验每个参考素材 URL 都返回 HTTP 200 且 content-type 符合预期。CDN 防盗链资产上的单个 403 是生产环境 failed 任务最常见的成因，且会浪费掉整次生成预算。在客户端加两行 HEAD 请求检查，就能避免整类失败。此外，使用稳定的内容寻址 URL（例如在路径里带 hash 或版本号），避免在活动中途更换素材时悄悄改变模型实际收到的内容。

错误处理与幂等

• 401 "API Key 无效"，Key 错误，或 Key 没有 video 权限范围。检查 Key 及其权限。
• 400 "模型不存在或未配置"，该后端尚未启用 seedance-2.5 路由。在 PixMind 上这处于 Coming Soon 状态。
• 4001 "余额不足"，请求合法但钱包没有积分，任务不会创建。
• 429 限流，按指数退避后重试；创建端点会强制执行按 Key 的并发和请求速率上限。如果频繁触发，请联系支持提升限额，或在短时间间隔内分批提交。
• 502 / 504 网关错误，瞬时问题；用相同的 Idempotency-Key 重试创建调用，让后端去重，从而不会启动第二个被计费的任务。
• 轮询超时，给尝试次数封顶（例如 100 × 5 秒，约 8 分钟），并把超时当作失败处理，只重试一次。

生产环境建议每次创建调用都带上 Idempotency-Key 请求头，让客户端重试不会启动第二个被计费的任务。为每个逻辑任务（而非每次 HTTP 尝试）使用一个 UUID，只生成一次并保存在你这边，这样同一个逻辑生成在重试、CI 重跑和队列回放中都能被去重。模式如下：当用户（或任务 runner）决定创建任务时生成 UUID，在第一次 HTTP 调用前先持久化，之后对该逻辑任务的所有重试都复用同一个。

第三方开发者资源

上面的契约是 PixMind 上的实现路径。若想更深入了解字节跳动底层模型和官方 API 表面，下面是开发者最常翻阅的资源，已于 2026-07-31 核对：

• BytePlus Seedance 2.5 资源页，ai.byteplus.com/lumina/en/resource/bytedance-seedance-2-5。字节跳动对 2.5 的官方阐述，围绕广告视频生成和产品演示展开。适合了解能力叙事以及字节自身瞄准的用例。已核对收录，2026-07-31。
• BytePlus ModelArk API 文档，通过字节云调用 Seedance 的官方开发者接入面。当你需要确认已接入路由实际暴露的字段名和模式时，可对照该文档的字段名和模式，并在客户端中镜像这些命名。
• 火山方舟（Volcano Engine Ark）文档，volcengine.com/docs/82379。同一模型家族的国内（中国）端点。异步提交+轮询的模式与 PixMind 路由一致，字段名和鉴权流程略有差异。已核对收录，2026-07-31；接入前请以实际路径为准。
• MakeFun AI 演示复刻指南，makefun.ai/seedance-2-5-demo-videos/。讲解如何复刻 BytePlus ModelArk 那套重度依赖参考素材的演示工作流。当你想先复刻官方效果再设计自己的提示词时很有帮助。
• 社区分析，Topview/Medium 上的 2.5 拆解、Pixo 关于 FORCE 的报道、以及 ToSea 的完整指南，都从编辑视角覆盖了工作流升级。适合补充背景，不适合查端点细节；技术细节务必以线上 API 为准。

开发者提示： 第三方指南过时很快。把任何一份都当作起点，在接入当天对照已接入路由核对端点路径、字段名和积分成本。本指南的端点和鉴权细节已于 2026-07-31 核对，但模型仍在滚动上线，生产上线前请再次核对。

Seedance 2.5 API 常见问题

Seedance 2.5 API 的端点是什么？

用 POST /api-platform/v1/generations 创建任务，再轮询 GET /api-platform/v1/task/{task_id} 直到 status 变为 ready。model 字段为 seedance-2.5。

如何对 Seedance 2.5 API 进行鉴权？

把 API Key 以 Authorization: Bearer <key> 的形式发送。也接受 X-API-Key 请求头。在 PixMind 控制台创建带 video 权限的 Key，并通过环境变量加载，不要硬编码进源码。

Seedance 2.5 API 在 PixMind 上线了吗？

路由已写好文档并就绪，后端访问正在最终调试，模型状态标记为 Coming Soon。/api-platform/models/seedance-2-5 页面提供端点和参数参考，过渡期可在 /ai-video/seedance-2-5 页面使用 Web 生成器。

一次 Seedance 2.5 请求可以发送多少个参考素材？

单次请求最多 50 路多模态输入，图片、视频、文本和音频合并计算。相比 Seedance 2.0 的 9 路有所提升。每个参考素材必须是可公开访问的 URL。

Seedance 2.5 API 是同步返回视频的吗？

不是。视频生成是异步的。创建调用返回 taskId，轮询任务端点直到 status 变为 ready，再读取 videoUrl。一段典型的 30 秒生成需要数分钟，因此客户端要按轮询设计，而不是阻塞等待。

限流和并发上限是多少？

创建端点会强制执行按 Key 的请求速率和并发上限。一旦超过，响应会返回 429，请按指数退避。对于批量负载（不止几个并发任务），请在短时间间隔内分批提交；如果频繁触发 429，请联系支持提升限额。具体数值按账号调优，因此在设计大规模批量任务前请用自己的 Key 实测。

Seedance 2.5 API 支持 Webhook 或回调吗？

已核对的 PixMind 路由只支持基于轮询的拉取，不支持推送回调。如果你的架构需要推送通知，可以跑一个调度器，由它轮询任务端点，并在 status 进入终态时向下游服务发出 Webhook。这样既保持接入简单，又能避免把流水线耦合到一个可能随环境变化的回调 URL 上。

可以同时跑多少个任务？

并发量由你 Key 的按 Key 上限和积分余额共同决定。对于 30 秒 1080p 的任务，预期是并行几个而不是几十个。请把实际上限当作"以自己账号为准"：先提交一小批校准任务，测量同时从 pending 进入 processing 的任务数，再据此规划队列大小。

API 返回什么视频格式？

ready 后的任务会返回指向标准 MP4 文件的 videoUrl，以及用作封面帧的 coverUrl。下载并按交付目标转码（Web 用带 fast-start 的 H.264，社交平台用竖版编码，剪辑母版用 ProRes）。生产环境不要直接热链 API 托管的 videoUrl，因为它不保证长期有效，请在 ready 后把文件复制到你自己的 CDN。

提交前如何检查积分？

在实时生成器中查看所选时长和分辨率对应的当前积分消耗，再核对钱包余额。如果余额过低，API 会返回 4001 "余额不足"，此时任务不会被创建。生产流水线建议加一道提交前的余额检查，当余额低于单任务阈值时提前中止，避免排队钱包覆盖不了的工作。

如何修复 "模型不存在或未配置" 错误？

这个 400 响应意味着你访问的后端端点上还没有启用 seedance-2.5 路由。在 PixMind 上，这处于 Coming Soon 状态，后端连接仍在最终调试。请确认调用的是文档中记载的 /api-platform/v1/generations 路径，且 model 为 "seedance-2.5"（小写、精确匹配）。如果两者都对但错误仍存在，说明该路由尚未对你账号开放，请关注 /api-platform/models/seedance-2-5 页面了解可用情况。

可以请求哪些分辨率和时长？

单次最长 30 秒；分辨率为 480p、720p、1080p 以及原生 4K。提交前请以实时生成器为准确认可选项，因为已接入的路由可能只暴露其中一部分。

Seedance 2.5 API 的定价公布了吗？

尚未公布。任何你在别处看到的按秒计价数字都请当作估算值。提交前请在实时生成器中查看所选时长和分辨率的当前积分，并让你的流水线设计能在不重写接入的情况下吸收价格更新。

开始用 Seedance 2.5 API 搭建

Seedance 2.5 API 是一套标准的异步视频生成契约：一次创建调用，一个轮询循环，一次下载。拿到带 video 权限的 Key 之后，上面的 curl 和 Python 示例就足够你交付第一版接入。对比表和流水线案例展示了如何把这套契约从单个片段扩展为可复用、能在客户修改、预算压力和截止日期下都撑得住的生产工作流。

→ 阅读 Seedance 2.5 API 路由参考完整文档，或在 API 接入最终完成前，在 Web 生成器中试用该模型。

对比所有 Seedance 路由

端点与鉴权细节于 2026-07-31 对照 PixMind api-platform 后端核对。第三方资源链接于 2026-07-31 核对。Kling API 对比字段标注为估算值，请以 Kling 官方文档为准。Seedance 2.5 定价尚未公布，相关内容标注为仅供估算。