UniLLM 视频生成 MCP

用一套统一接口生成视频，屏蔽各家协议差异。本 Skill 背后是一个 MCP Server。

支持 8 家厂商：豆包 Seedance（火山方舟）、通义万相 Wan、智谱 CogVideoX、MiniMax Hailuo、快手可灵 Kling、SiliconFlow，以及海外 Runway 与任意自定义端点。

> <skill-directory> 指本 Skill 所在目录，而非用户项目目录。
> MCP Server 源码位于 <skill-directory>/server/。

🎬 核心：视频要素必须明确

视频生成和图片生成最大的区别：参数错了代价极高。 一次视频生成要等 1~5 分钟、花真金白银，所以本 MCP 把分辨率、屏幕比例、时长当作一等公民显式建模 —— 每个调用的返回里都会明确标注这三项，参数不匹配时会在发起任务前就调整好并告知，绝不静默改参数。

三层视频要素

> 关键理解：分辨率与屏幕比例共同决定输出像素尺寸。
> 1080p + 16:9 = 1920x1080，1080p + 9:16 = 1080x1920 —— 都是 1080p，只是画幅方向不同。
> 「短边」决定档位：1920x1080 与 1080x1920 的短边都是 1080。

屏幕比例速查

> 用 video_elements() 可查看完整速查表；video_elements(ratio="9:16") 可查某比例下的全部可用组合。

参数规范化：不会静默改

⏱️ 核心：视频是异步长任务

一次视频生成通常需要 1~5 分钟。本 MCP 提供两种用法：

方式 A：一站式（省事，会阻塞）

video_generate(...)   # 提交 + 轮询 + 下载，直到拿到视频文件

适合：单个任务、不在意等待。默认最长等 10 分钟（可调）。

方式 B：两步走（推荐，不阻塞）

video_submit(...)          → 立刻拿到 taskId（不等）
video_task_status(taskId=...)  → 稍后查询；成功则自动下载

适合：批量提交多个任务；或不想让单次工具调用长时间阻塞。
好处：工具调用超时 ≠ 任务失败 —— 拿到 taskId 就永远能事后查询。

工具一览

> 工具在 Agent 中的实际名称形如 mcp__plugin_unillm-video_unillm-video__video_generate，调用时用短名即可。

厂商能力矩阵

屏幕比例表达方式（ratioMode）：各厂商不同，本 MCP 已自动处理 ——
ratio-field（独立 ratio 字段：豆包、可灵、Runway）、
size-field（由像素推导：万相、智谱、SiliconFlow）、
from-image（首帧决定：MiniMax）。

分辨率档位说明

When to Use

• 用户要做文生视频 / 图生视频：广告片、短视频、分镜预览、产品演示、动态海报。
• 用户要生成特定规格的视频：竖屏短视频（9:16）、横屏（16:9）、超宽（21:9）、4K。
• 用户需要首尾帧控制：让画面从 A 平滑过渡到 B。
• 用户要批量生成多个视频：用 video_submit 并行提交。
• 用户问「支持哪些视频模型」「某厂商支持什么分辨率/比例」「密钥配了没有」。
• 需要把图片 MCP 的产出「动起来」：先用 unillm-image 出图，再用本 MCP 当首帧。

When NOT to Use

• 只要静态图片 —— 请用配套的 unillm-image 图片 MCP（更快更便宜）。
• 需要视频剪辑 / 转码 / 拼接 —— 本 MCP 只做生成，不做后期处理。
• 需要视频理解 / 摘要 —— 请用 unillm-multimodal 多模态 MCP。

参数说明

video_generate / video_submit

video_task_status

密钥配置

密钥只从环境变量读取，不会写入任何文件，也不会回显完整值。

export ARK_API_KEY="xxxxxxxx"          # 豆包 Seedance / 火山方舟（国内直连）
export DASHSCOPE_API_KEY="sk-xxxxxx"   # 通义万相（国内直连）
export ZHIPU_API_KEY="xxxxxxxx"        # 智谱 CogVideoX（国内直连）
export MINIMAX_API_KEY="xxxxxxxx"      # MiniMax Hailuo（国内直连）
export KLING_API_KEY="xxxxxxxx"        # 快手可灵（需 AccessKey+SecretKey 签发的 JWT）
export SILICONFLOW_API_KEY="sk-xxxx"   # SiliconFlow（国内直连）
export RUNWAY_API_KEY="key_xxxx"       # Runway（需代理）

配置后用 video_provider_status(provider="doubao", liveProbe=true) 真实探测（不生成视频、不产生费用）。

调用示例

1. 竖屏短视频（抖音 / TikTok）

video_generate(
  prompt="一只橘猫在月光下的屋顶上伸懒腰，缓慢推进镜头，电影感，暖色调",
  provider="doubao",
  resolution="1080p",
  ratio="9:16",          # ← 竖屏
  duration=5
)

2. 横屏电影感（超宽银幕）

video_generate(
  prompt="雪山日出，镜头缓慢横移，云海翻涌，航拍视角，电影级画质",
  provider="doubao",
  resolution="1080p",
  ratio="21:9",          # ← 仅豆包支持超宽
  duration=5
)

3. 用像素直接指定

video_generate(
  prompt="水墨风格的远山，雾气流动",
  provider="qwen",
  size="1920x1080",      # ← 自动反推 1080p + 16:9
  duration=5
)

4. 图生视频（让图片动起来）

# 先用图片 MCP 出一张图
# image_generate(prompt="赛博朋克城市夜景", provider="doubao")
# → 得到 ./unillm-images/doubao-t2i-xxx.png

video_generate(
  prompt="镜头缓慢向前推进，霓虹灯闪烁，雨滴落下",
  provider="kling",
  image="./unillm-images/doubao-t2i-xxx.png",   # ← 首帧
  ratio="16:9",
  duration=5,
  mode="pro"                                     # ← 1080p
)

5. 首尾帧控制（A → B 过渡）

video_generate(
  prompt="画面从白天平滑过渡到黄昏",
  provider="doubao",
  image="./frame-a.png",        # 首帧
  lastFrame="./frame-b.png",    # 尾帧
  duration=5
)

6. 异步批量提交（不阻塞）

# 并行提交 3 个任务
video_submit(prompt="...", provider="doubao", ratio="9:16", duration=5)
video_submit(prompt="...", provider="qwen",   ratio="9:16", duration=5)
video_submit(prompt="...", provider="zhipu",  ratio="9:16", duration=5)

# 拿到 3 个 taskId 后，间隔 15~30 秒逐个查询
video_task_status(taskId="...", provider="doubao")

7. 查询视频要素速查表

video_elements()                    # 全部档位与比例含义
video_elements(ratio="9:16")        # 哪些厂商支持竖屏、各是什么尺寸

选型建议

迭代策略：短视频调优的正确姿势是「先低分辨率试运动，再高分辨率定稿」。
运动不对的时候，1080p 只是更贵地展示错误。建议 480p/720p 迭代 → 定稿切 1080p。

错误处理

注意事项

1. 视频贵：一次生成可能数元。用 480p/720p 迭代，别用 1080p 试错。
2. 要素必看：返回里的 spec 字段明确给出实际使用的分辨率/比例/像素/时长，以它为准。
3. 别重复提交：轮询是查同一个 taskId，不要反复调 video_generate（那会重复扣费）。
4. 可灵鉴权特殊：需要 AccessKey + SecretKey 签发的短期 JWT，不是普通 API Key。
5. 比例由首帧决定的厂商：MiniMax 图生视频时输出比例跟首帧图走，ratio 参数会被忽略（返回中会提示）。
6. 4K 仅智谱、21:9 仅豆包 —— 选错了会被自动降级。
7. 首尾帧模式：豆包要求 ratio="adaptive"，本 MCP 会自动处理。

可配置项

安装与自检

cd <skill-directory>/server
npm install && npm run build
node dist/index.js    # stdio 启动；正常时 stderr 输出启动日志

若 MCP Server 未被加载，检查：
1. server/dist/index.js 是否已构建；
2. .mcp.json 中 ${CODEBUDDY_PLUGIN_ROOT} 是否被正确展开；
3. 插件是否在 settings.json 的 enabledPlugins 中启用。

> 配套技能：unillm-image（图片生成）、unillm-multimodal（多模态对话）、unillm-text（纯文本对话）。
> 四者共用同一套框架，可独立安装，也可组合使用 —— 例如「图片 MCP 出图 → 视频 MCP 让图动起来」。