seedance-mcp

一个 MCP 服务器，让 Claude Code 能够使用 BytePlus ModelArk Dreamina Seedance 2.5 生成视频。

用自然语言向 Claude Code 描述视频需求；它会将任务提交给 BytePlus，轮询直到渲染完成，然后返回视频 URL 以及 BytePlus 报告的元数据。

1. 功能概述

通过 MCP stdio 提供六个工具：

它处理了那些容易出错的部分：将本地图片和音频编码为 API 期望的 Base64 数据 URI 格式，在请求发送前强制检查每个模型的参数限制，用退避策略重试临时故障，以及确保 API 密钥不会出现在任何日志行或错误消息中。

2. 前提条件

• Python 3.11+

• uv — brew install uv 或 curl -LsSf https://astral.sh/uv/install.sh | sh

• Claude Code 2.x

• 一个 BytePlus ModelArk 账户，拥有 API 密钥并已激活 Seedance 模型。

3. BytePlus 配置

1. 创建 API 密钥：ModelArk 控制台 → API 密钥。

2. 激活模型。 Seedance 2.5 默认未启用。BytePlus 要求满足以下条件之一：

   • 账户余额超过 30 美元，或

   • 购买了 30 美元或更高档位的 AI 储蓄计划，或

   • 拥有剩余配额的 Seedance 资源包。

   在 ModelArk → 模型激活 → 计算机视觉 下激活。如果没有激活，即使密钥本身有效，任务创建也会因授权错误而失败。

3. 记下你的区域。下面的默认基础 URL 是 ap-southeast（新加坡）。如果你的账户在其他区域配置，请相应设置 BYTEPLUS_BASE_URL——在一个区域创建的任务在另一个区域不可见。

4. 安装

git clone <this repo> ~/code/seedance-mcp   # or just use the directory you already have
cd ~/code/seedance-mcp
uv sync

验证：

uv run pytest -q          # 93 tests, all offline against mocked HTTP
uv run ruff check .

5. .env 设置

cp .env.example .env

然后填写一个必需的变量：

BYTEPLUS_API_KEY=your-modelark-api-key

其他所有变量都是可选的，并且已有默认值：

BYTEPLUS_BASE_URL=https://ark.ap-southeast.bytepluses.com/api/v3
SEEDANCE_MODEL_ID=dreamina-seedance-2-5-260628

.env 已被 gitignore。密钥仅从环境变量读取——此服务器永远不会将其写入磁盘，不会记录，并且在 API 错误消息到达 Claude 之前会将其清除。

6. 选择 Seedance 2.5 模型 ID

Seedance 2.5 是一个共享的、普遍可用的模型 ID——你不需要创建专用端点。默认值为：

dreamina-seedance-2-5-260628

注意 dreamina- 前缀。这是 BytePlus 命名中一个真实存在的不一致之处：2.x 的 Dreamina 模型带有此前缀，而 1.x 的 ID 则没有（seedance-1-5-pro-251215）。将 1.x 形状的 ID 复制给 2.5 使用是导致“模型未找到”错误的最常见原因。

在 ModelArk 模型列表 中确认你账户的当前 ID。

如果你更喜欢专用端点（用于按端点限速、预付费计费或监控），请在控制台中创建一个，并将其端点 ID 填入 SEEDANCE_MODEL_ID：

SEEDANCE_MODEL_ID=ep-20260817120000-abcde
SEEDANCE_MODEL_PROFILE=seedance-2.5

只有在那种情况下才需要 SEEDANCE_MODEL_PROFILE：一个 ep-... 格式的 ID 并不能说明背后是哪个模型，因此没有它，服务器无法在本地验证参数，而是将所有参数传递给 API 进行验证。

7. 注册到 Claude Code

在此目录下（使用绝对路径——Claude Code 可能从任意工作目录启动服务器）：

claude mcp add \
  --transport stdio \
  --scope user \
  byteplus-seedance \
  -- uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp

--scope user 使其在所有项目中可用。使用 --scope project 可通过 .mcp.json 与仓库协作者共享，或省略 --scope 仅用于当前项目。

服务器会从其自身目录读取 .env，因此无需 -e 标志。如果你更愿意显式传递密钥：

claude mcp add --scope user byteplus-seedance \
  -e BYTEPLUS_API_KEY=your-key \
  -- uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp

8. 验证

claude mcp list

预期会看到类似这样的行：

byteplus-seedance: uv --directory /Users/alban/code/seedance-mcp run python -m seedance_mcp - ✓ Connected

然后在 Claude Code 中，/mcp 会列出服务器及其六个工具。可以这样问：

列出我最近的 Seedance 任务。

这会测试身份验证和连接性，而不会消耗生成配额——返回空列表也是成功。如果密钥错误，你会收到明确的 HTTP 401 消息。

要进行端到端检查并实际渲染一个文件，请使用 §10 中成本最低的方案。

9. Claude Code 提示示例

Generate a 10-second 1080p cinematic video of Tokyo at night using Seedance 2.5.

Use ./assets/reference.png as the visual reference and generate a slow cinematic push-in shot.

Create the video and wait until generation finishes.

Generate a 15-second 9:16 vertical clip of a surfer at sunrise, no audio, and give me the URL.

Use ./assets/first.png as the first frame and ./assets/last.png as the last frame,
6 seconds, and wait for it.

Check the status of task cgt-20260817... and download the video if it's ready.

Download task cgt-20260818061514-8t2lv into ./renders/ and keep the last frame too.

Cancel task cgt-20260817... — I queued the wrong prompt.

10. 成本与时间

生成按输出秒数计费，并根据分辨率和模型缩放。验证整个流程是否正常工作的最便宜方式是生成一个 4 秒的 480p 片段——4 秒是所有 Seedance 2.x 模型接受的最短时长。

免费检查，不消耗生成配额：

List my recent Seedance tasks.

最便宜的真实生成。 Seedance 2.0 mini 是账户上最便宜的模型；在持续到 2026 年 9 月 7 日的促销活动期间，其 720p 输出起价约为 0.03 美元/秒，480p 则更低：

Using Seedance model seedance-2-0-mini-260615, generate a 4-second 480p video, 16:9, no audio,
prompt: "a red balloon floating up against a blue sky". Then wait for it and give me the URL.

Seedance 2.5 默认路径的最便宜测试——值得单独运行，因为 2.5 是不同的模型激活和不同的价格层级：

Generate a 4-second 480p Seedance 2.5 video, 16:9, no audio,
prompt: "a red balloon floating up against a blue sky". Wait for it and give me the URL.

实测基准

来自 2026-08-18 一次真实的 Seedance 2.5 文本转视频运行：

这是最低值：最短时长、最低分辨率、无参考媒体。这也为 seedance_wait_for_video 设定了预期，其 900 秒的默认超时是针对比此任务重一个数量级的作业设计的。

从该基准进行缩放是外推，而非实测——用量与输出秒数和像素数相关，因此一个 10 秒的 1080p 片段大约是 2.5 倍的秒数和约 5 倍的像素数，即大约为此运行的 10 倍。请将其视为规划估算，并对照你自己的账单进行确认。

duration 的成本陷阱

Seedance 2.5 的 duration 默认值为 -1，这会让模型选择最长 30 秒的任意长度。由于按输出秒数计费，一个未指定时长的请求可能花费约 7 倍于预期的 4 秒测试。在任何对成本敏感的运行中，请显式指定秒数——该工具会直接传递该值，而 4 秒是最低值。

还有两个小提示：480p 和 720p 不享受当前的 2.5 促销折扣（仅 1080p 有折扣），因此 480p 在绝对成本上仍然最便宜——折扣根本不适用于它。另外，no audio 主要缩短生成时间；文档中没有任何内容表明它会降低价格。

11. 故障排除

12. 支持的 Seedance 2.5 功能

任务类型（互斥——BytePlus 拒绝混合类型）：

• 文本转视频——仅提示词。

• 图片转视频——first_frame，可选加上 last_frame。输出将精确以这些图片开始和结束。

• Omni 参考转视频——最多 30 张参考图片、10 个参考视频和 10 个音频片段，允许仅音频输入。在提示词中使用 @Image 1、@Video 2 引用素材。涵盖三个子任务：参考转视频、视频编辑和视频扩展——通过 omni_reference_task_type 控制。

输出控制

媒体输入

提示词支持英语、西班牙语、印度尼西亚语、葡萄牙语、日语、马来语、泰语、阿拉伯语、越南语和韩语。建议控制在约 1000 个英语单词以内。

保存输出。 seedance_download_video 接受一个任务 ID，自行查找当前 URL，并将文件流式传输到磁盘。默认保存为 ./<task_id>.mp4；可通过 output_path 指定文件路径或现有目录。除非设置 overwrite: true，否则不会覆盖已有文件；如果下载中断，会自动清理不完整的文件。当任务创建时设置了 return_last_frame，还可以通过 include_last_frame 获取结尾 PNG 图片。有两个明确的限制：下载使用其自身的未认证 HTTP 客户端，因此 ModelArk 密钥永远不会发送到存储服务器；并且 URL 的主机名必须以 .volces.com、.bytepluses.com 或 .byteplus.com 结尾——这是一个专用的 Seedance 输出下载器，而非通用下载工具。

该服务器也支持旧版模型，通过 model 工具参数或 SEEDANCE_MODEL_ID 指定——Seedance 2.0 / 2.0 fast / 2.0 mini、1.5 pro、1.0 pro 和 1.0 pro fast——并针对各自限制进行验证（例如 4K 对 2.0 有效，但对 2.5 无效）。

13. 已知 API 限制

• 生成是异步的。 没有任何操作能同步返回视频；一个 5–10 秒的片段通常需要几分钟，在 1080p 下时间更长。

• Seedance 2.5 上不可设置 seed 或 camera_fixed。 当前的 API 参考仅将这两项列为 Seedance 1.5 pro、1.0 pro 和 1.0 pro fast 的输入参数。此服务器会针对 2.5 版本明确拒绝这些参数，并给出明确提示，而非静默忽略。请在提示词中描述所需的镜头行为。（旧的 Seedance 1.x 教程和第三方示例仍显示这些参数——它们已不再适用于 2.5 版本。）

  在真实的 2.5 运行中观察到：任务的响应仍会报告一个 seed（以 VideoResult.seed 形式呈现，例如 80969），因为模型内部会选择一个。因此，你可以看到是哪个种子生成了该片段，但无法要求重现——2.5 版本的生成是不可复现的。

• Seedance 2.5 上不支持 frames。 通过帧数控制亚秒级时长是 1.0 pro 的功能。

• 无法上传本地视频。 图片和音频有 Base64 格式支持；视频则没有。

• 64 MB 请求体上限。 内嵌多张大图片会达到此限制；服务器会在发送前检查，并提示你改用 URL。

• 真人面孔受到限制。 Seedance 2.x 会拒绝包含真人面孔的参考图片和视频，除非这些内容来自你自己账户（30 天内）的先前 Seedance 输出、预设的数字角色，或经过授权的真人资产。

• 只有排队中的任务可以取消。 一旦任务开始运行，它会一直执行到完成。

• 输出 URL 的有效期为 24 小时，Seedance 2.5 上限为 100 次下载。这两个限制都嵌在签名的 URL 本身中——返回的链接带有 X-Tos-Expires=86400 和 X-Tos-Max-Requests=100。没有重新签发的端点，且 seedance_list_tasks 只能返回仍在有效期内的 URL。请使用 seedance_download_video 保存任何值得保留的内容；一旦窗口关闭，唯一的补救措施是重新生成。

• 任务记录保存 7 天。

• 参考媒体的时长限制不会在本地检查。 参考视频和音频的单片段（2–30 秒）和总时长（30 秒）限制需要媒体探测；服务器没有为此添加解码器依赖，因此由 BytePlus 执行这些限制，并在任务错误中报告。

• 价格和限制会发生变化。 src/seedance_mcp/capabilities.py 中的能力表是根据 2026-08-17 的 BytePlus 文档抄录的；如果 BytePlus 发布新的模型修订版，请重新核对。

14. 项目结构

seedance-mcp/
├── pyproject.toml
├── README.md
├── .env.example
├── .gitignore
├── src/seedance_mcp/
│   ├── __init__.py
│   ├── __main__.py        # stdio entry point
│   ├── server.py          # the six MCP tools
│   ├── client.py          # BytePlus HTTP client: retries, error parsing
│   ├── payload.py         # request building + validation
│   ├── capabilities.py    # per-model limits from the official docs
│   ├── media.py           # local file -> data URI, with validation
│   ├── models.py          # typed request/response models
│   ├── config.py          # environment configuration
│   └── errors.py          # error types + secret redaction
└── tests/

capabilities.py、payload.py 和 media.py 是对概要中所述结构的补充：每个模型约束表、请求构建器和媒体处理都有实际的逻辑和各自的测试，如果将它们折叠到 server.py 或 models.py 中，会使两者都难以阅读。

15. 来源

上述所有 API 细节均已对照当前官方 BytePlus 文档进行验证：

• 创建视频生成任务

• 获取视频生成任务

• 列出视频生成任务

• 取消或删除视频生成任务

• Dreamina Seedance 2.5 教程

• 模型列表

• 视频生成 API 教程