HyperFrames MCP

HyperFrames MCP 是一个托管的 Model Context Protocol 服务器，让你可以从 Claude.ai 或 ChatGPT 内部创建、编辑、预览和渲染 HyperFrames 视频合成。

ℹ️ Note

Beta 中。 功能和定价可能会变化。发现 bug 或有反馈？在 GitHub 上提交 issue。

你能做什么

• 从自然语言提示创建合成
• 通过对话编辑现有合成——"把标题放大 2 倍"、"添加嗨风格字幕"
• 在聊天中通过视频播放器小部件内联预览结果
• 渲染为 mp4、webm 或 mov——输出 URL 流式传输回聊天
• 查看你之前创建的合成
• 检查你的渲染额度

compose 背后的 agent 内置了 25+ 个 HyperFrames 特定的 skill——排版、调色板、运动原理、GSAP 效果、音频响应式动画、字幕、语音生成。你不必直接指定这些；描述你想要的视频，agent 会选择正确的工具。

ℹ️ Note

寻找开源 CLI？参见快速开始。MCP 是一个托管产品，用于在 LLM 聊天中进行零安装创作。CLI 给你完整的渲染和运行时控制；MCP 给你即时创作和云端渲染。

设置

1. 获取 HeyGen 账户

MCP 需要 HeyGen 账户进行身份验证和额度。如果你没有账户，请在 heygen.com 注册。

2. 添加连接器

Claude.ai

打开设置 → 连接器

在 Claude.ai 网页版或桌面版：设置 → 连接器 → 添加自定义连接器。

输入 URL

粘贴：

https://mcp.heygen.com/mcp/hyperframes

登录 HeyGen

OAuth 在新窗口中打开。授权 HyperFrames 连接器访问你的 HeyGen 账户。

开始新对话

打开一个新的 Claude.ai 对话。试试：

为 你的产品 制作一个 10 秒的产品介绍视频，带弹跳字幕和高能配乐。

ChatGPT

打开 Apps & Connectors

在 ChatGPT：设置 → Apps & Connectors → Add MCP server。

输入 URL

粘贴：

https://mcp.heygen.com/mcp/hyperframes

登录 HeyGen

通过 OAuth 授权。

开始新对话

打开新对话。与 Claude.ai 中相同的提示。

可用工具

MCP 向 LLM 暴露六个工具。你不需要直接调用它们——模型根据你的消息选择正确的工具。

compose

创作新合成或对现有合成应用编辑。HyperFrames agent 根据你的自然语言提示内部处理语音选择、字幕、blocks、布局、过渡、颜色和计时。

由以下提示触发：

• "制作一个关于 主题 的 30 秒产品介绍" → 创建全新合成
• "将标题字体改为粗衬线体" → 编辑最近的合成
• "在 CTA 之前添加闪现过渡" → 应用结构化编辑

返回： 合成引用（id、标题、缩略图）加上内联播放器小部件。运行期间会流式传输进度通知，让你可以看到 agent 正在做什么——"起草大纲..."、"选择语音和风格..."、"生成 HTML..."、"渲染预览帧..."

list_compositions

列出你之前创建的合成。最新优先，分页。

由以下提示触发： "显示我最近的视频"、"我昨天做了什么？"

get_composition

获取单个合成的元数据以及内联播放器小部件。

由以下提示触发： "再次打开那个视频"、"显示我关于 主题 做的那个"

render_video

提交云端渲染。默认为 mp4，30fps。

格式选项：

帧率选项： 24、30（默认）、60。

返回： 已渲染视频的 URL（如果渲染在 25 秒内完成）或用于轮询的 job_id。无论哪种方式，内联渲染进度小部件显示实时状态。

由以下提示触发： "渲染这个"、"导出为 webm"、"以 60fps 渲染用于编辑"。

get_render_status

轮询进行中的渲染。当 render_video 返回 job_id（长时间渲染）时由模型内部使用。

get_credits

返回你的等级和剩余额度。

由以下触发： "我还剩多少渲染次数？"、"我的计划是什么？"

提示技巧

明确你想要什么

agent 有很大的创意自由度——给它足够的方向来好好利用它。

通过对话迭代

合成存在后，agent 加载当前状态并就地应用编辑。继续与它对话。

你：    "我的应用的 20 秒产品介绍，深色主题，嗨风格"
Agent：[合成 + 播放器小部件出现]

你：    "把 logo 放大并给 CTA 添加脉冲动画"
Agent：[更新的播放器小部件]

你：    "渲染为带 alpha 的 webm"
Agent：[渲染进度小部件，然后带下载链接的播放器小部件]

引用你现有的 HeyGen 素材

如果你已将 logo、品牌语音、字体或其他素材上传到 HeyGen 账户，agent 可以使用它们。只需说 "使用我的 logo" 或 "使用我的 Sarah 品牌语音"。agent 按名称和最近使用解析素材。

提前选择正确的格式

如果你有特定用例，请提及输出格式：

• "渲染为 mp4" — 默认，社交媒体
• "渲染为带 alpha 的 webm" — 稍后合成的透明叠加
• "渲染为 mov 用于 After Effects" — ProRes 用于编辑

调试

使用 MCP Inspector 检查 MCP

对于构建集成或调试工具响应的开发者，MCP Inspector 让你准确查看暴露了哪些工具以及它们返回什么：

npx @modelcontextprotocol/inspector npx -y mcp-remote https://mcp.heygen.com/mcp/hyperframes

在 Inspector 的浏览器标签页中完成 OAuth 流程。认证后，你可以使用自定义参数调用每个工具并查看原始响应，包括 tool_data 和 widget_data。

查看进度通知

MCP 在长时间运行的 compose 和 render_video 调用期间发出 MCP notifications/progress 事件。宿主（Claude.ai 或 ChatGPT）内联显示它们：

你：    "为我制作一个 30 秒的产品介绍"
Agent：[调用 compose]
↳ "起草大纲..."           ← 进度通知
↳ "选择语音和风格..."     ← 进度通知
↳ "生成 HTML..."          ← 进度通知
↳ "渲染预览帧..."         ← 进度通知
↳ [合成 + 播放器小部件]
Agent："这是你的视频——[播放器]"

如果进度在中途停止，运行失败。agent 的下一条消息应该解释出了什么问题。

常见问题

报告问题

有关 bug 或功能请求，请在 github.com/heygen-com/hyperframes/issues 提交 issue。包含：

• 你使用的提示
• composition_id 和 job_id（如果适用）——在工具响应详情中可见
• 你期望的与实际发生的描述
• 宿主（Claude.ai 网页/桌面版、ChatGPT 等）

限制

• 仅云端渲染。 所有渲染都在 HeyGen 基础设施上运行。如需本地渲染，请使用 CLI。
• 单用户。 每个合成由一个 HeyGen 账户拥有。v1 版本中没有团队共享。
• 不能从聊天上传二进制文件。 你可以通过 Web UI 引用已上传到 HeyGen 的素材，但 MCP 目前不接受通过聊天的新文件上传。先通过 app.heygen.com 上传，然后按名称引用素材。
• 宽高比： 16:9、9:16、1:1、4:5。其他比率回退到最接近的匹配。
• 没有细粒度编辑工具。 编辑通过 agent 进行。对于像素级精确控制，使用 CLI 和 Claude Code 或 Cursor 等编程 agent。
• 小部件渲染需要支持 MCP 小部件的宿主。 Claude.ai 网页/桌面版和 ChatGPT（Apps SDK）今天支持小部件。纯文本 MCP 客户端（Claude Code CLI、Cursor、Windsurf）将看到可点击的预览 URL——完整的文本模式支持在路线图上。

与开源框架的关系

HyperFrames 本身是开源的——HTML 合成格式、CLI、渲染器和 player。你可以本地使用 HyperFrames，无需 MCP。

MCP 是一个 HeyGen 托管的产品，包装了：

• HyperFrames 合成 agent（创作合成的 LLM）
• HeyGen 的云端渲染管线
• HeyGen 的语音 / TTS / 素材库
• OAuth、额度和等级管理

下一步

• 快速开始 使用开源 CLI 本地试用 HyperFrames。
• 提示指南 使用 AI agent 获得最佳结果的技巧。
• 目录 浏览 agent 使用的 50+ 个可直接使用的 blocks。
• 示例 可克隆的参考合成。