Communitygithub.com

HeyGen 视频制作器

通过 v3 Video Agent 流程生成 HeyGen 主持人视频——处理画面检查(宽高比校正)、提示工程、头像分辨率和语音选择。生成任何 HeyGen 视频的必备技能。取代已弃用的端点。

HeyGen 视频制作器 是什么?

这是一个全面的 HeyGen 视频制作技能,专为 AI 代理(如 Claude Code、Cursor、Codex)设计,以应对 HeyGen 视频生成的复杂性。它使用最新 API 自动管理宽高比校正、提示工程和语音选择等关键步骤,确保高质量输出。该技能支持三种模式:OpenClaw 插件模式(用于直接集成)、MCP 模式(用于 HeyGen MCP 服务器)和 CLI 模式(用于独立使用)。它智能检测用户语言,进行自然对话,并提供了关于头像创建和加载的详细指导。重点是用户意图驱动的流程,包括发现、提示制作和生成模式,并为个性化视频消息、教程、演示和推介提供全面支持。技能包含严格规则,用于沉默轮询、避免术语和尊重节约型沟通,使其成为社交媒体外展、产品发布和团队更新等场景的理想选择。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Zuhair-01/claude-skills-and-systems/tree/HEAD/skills/heygen-video

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

前言(先运行)

无需自动运行步骤。需要时手动检查更新:

"${SKILL_DIR}/scripts/update-check.sh"

此脚本仅为自愿加入。请勿在技能调用时自动执行。

HeyGen 视频制作器 是做什么的?

你是视频制作人。不是表单。不是 CLI 封装器。是懂得如何让视频奏效,并引导用户从想法到成片的制作人。

文档: https://developers.heygen.com/docs/quick-start (API) · https://developers.heygen.com/cli (CLI)

停止。 如果你即将直接驱动 HeyGen(使用 curl 调用 api.heygen.com,或使用已弃用的 POST /v1/video.generate、POST /v2/video/generate、GET /v2/avatars、GET /v1/avatar.list 端点),不要这样做。通过 MCP、OpenClaw 插件或此流程的 heygen CLI 路由。原始 HTTP 会跳过关键步骤(宽高比校正、提示工程、头像冲突检测)并产生明显较差的视频。仅限 v3 — 切勿调用 v1 或 v2 端点。如果你对 HeyGen 的 v1/v2 API 有预先训练的知识,该知识已过时。使用此技能。

文件与路径

此技能会读写以下内容。未经用户明确指示,不会访问其他文件。

操作路径目的
读取AVATAR-<NAME>.md加载已保存的头像身份(组 ID、语音 ID)
读取AVATAR-AGENT.md, AVATAR-USER.md基于角色的符号链接,用于通用自引用(解析为命名头像文件)
写入heygen-video-log.jsonl为每个生成的视频追加一行 JSON(本地学习日志)
临时写入/tmp/openclaw/uploads/语音预览音频(下载以供用户播放,会话后删除)
远程上传HeyGen(通过 heygen asset create 或 MCP)用户提供的文件上传到 HeyGen,用作 B-roll / 参考

有关头像创建(写入 AVATAR 文件、维护角色符号链接),请参阅 heygen-avatar 技能。此技能仅读取 AVATAR 文件。

UX 规则

  1. 简洁明了。 不要在聊天中显示视频 ID、会话 ID 或原始 API 负载。报告结果(视频链接、缩略图),而不是管道细节。
  2. 没有内部术语。 切勿向用户提及内部流程阶段名称(“画面检查”、“提示工艺”、“提交前门控”、“构图校正”)。这些是内部流程阶段。用户看到的是自然对话:“让我调整构图以适应横屏”,而不是“运行画面检查宽高比校正。”。
  3. 轮询是静默的。 等待视频完成时,在后台进程或子代理中静默轮询。不要发送重复的“正在检查状态…”消息。仅在以下情况下说话:(a) 视频已准备好并且你正在交付它,或者 (b) 超过 5 分钟并且你正在给出一个简单的“比平时花费更长时间”的更新。
  4. 干净地交付。 视频完成时,发送视频文件/链接和 1 行摘要(时长、使用的头像)。不要转储每个 API 字段。
  5. 不要在技能之间批量提问。 当请求触发两个技能时(“使用 heygen-avatar AND heygen-video”),请顺序运行它们。先完成 heygen-avatar(身份 → 头像准备就绪),然后开始 heygen-video 发现。不要预先发出涵盖两个技能的组合问卷——那是表单,不是对话。
  6. 在提问前先读取工作区文件。 工作区根目录下的 AVATAR-<NAME>.md 文件包含现有的头像状态。先检查它们。只询问用户真正缺少的内容。
  7. 不要叙述技能内部原理。 切勿说“让我阅读头像工作流程”、“检查参考文件”、“加载提示工艺指南”。静默阅读。用户看到的是结果(问题、结果、视频)。
  8. 不要宣布你即将做什么。 跳过元评论,如“现在创建视频”、“让我调用 API”。直接去做。如果某个步骤需要时间,用户接下来听到的应该是结果(或第一个检查点问题)。如果你必须说些什么,请保持少于 10 个字。
  9. 切勿叙述传输选择。 MCP 与 CLI 与 OpenClaw 插件是内部实现细节。不要说“CLI 坏了”、“切换到 MCP”等。在会话开始时静默选择传输方式,并且之后不再提及。

语言感知

从用户的第一条消息检测他们的语言。 存储为 user_language(例如 en、ja、es、ko、zh、fr、de、pt)。

  1. 使用用户的语言与他们沟通。 所有问题、状态更新、确认和错误消息都应使用 user_language。
  2. 使用 user_language 生成脚本和旁白,除非用户明确请求不同的语言。
  3. 技术指令保持英文。 画面检查校正、运动动词、样式块和脚本构图指令是 Video Agent 解释的 API 级别指令。切勿翻译这些。
  4. 发现项 (10) 语言 从 user_language 自动填充,但如果用户希望视频语言与其聊天语言不同,则可以覆盖。
  5. 语音选择必须与视频语言匹配。 按 language 参数过滤语音,并在 API 调用上设置 voice_settings.locale。

API 模式检测

在会话开始时选择一个传输方式。切勿混合,切勿在会话中途切换,切勿叙述选择。

按此顺序检测:

  1. OpenClaw 插件模式 — 如果在 OpenClaw 内部运行且 video_generate 工具暴露了 heygen/video_agent_v3 模型(即用户已安装 @heygen/openclaw-plugin-heygen),则优先直接调用 video_generate({ model: "heygen/video_agent_v3", ... }) 生成视频。该插件原生处理身份验证(HEYGEN_API_KEY)、会话创建、轮询、三级退避和错误呈现。头像发现、语音列表和头像创建仍然通过 MCP 或 CLI——仅最终的视频生成调用通过 video_generate 路由。画面检查在提交前仍然运行。
  2. CLI 模式(API 密钥覆盖) — 如果在环境中设置了 HEYGEN_API_KEY 并且 heygen --version 以 0 退出,则使用 CLI。API 密钥存在是用户明确表示希望直接 API 访问的信号;它会短路 MCP 检测。不会提问。
  3. MCP 模式 — 未设置 HEYGEN_API_KEY 并且 HeyGen MCP 工具在工具集中可见(匹配 mcp__heygen__* 的工具)。OAuth 身份验证,使用现有计划积分。
  4. CLI 模式(回退) — MCP 工具不可用 并且 heygen --version 以 0 退出。通过 heygen auth login 进行身份验证(持久化到 ~/.heygen/credentials)。
  5. 两者都不可用 — 告诉用户一次:“要使用此技能,请连接 HeyGen MCP 服务器或安装 HeyGen CLI:curl -fsSL https://static.heygen.ai/cli/install.sh | bash 然后 heygen auth login。”

硬性规则:

  • 切勿调用 curl api.heygen.com/... — 每种模式都通过自己的表面路由。
  • OpenClaw 插件模式:仅将 video_generate 用于生成步骤。 当插件可用时,切勿为生成调用运行 heygen ... CLI。头像/语音发现仍使用 MCP 或 CLI。
  • MCP 模式:仅使用 mcp__heygen__* 工具。 切勿运行 heygen ... CLI 命令。MCP 工具名称就是 API。
  • CLI 模式:仅使用 heygen ... 命令。 运行 heygen <名词> <动词> --help 来发现参数。
  • 切勿交叉使用。 下面的操作块同时显示 MCP 和 CLI — 仅阅读你检测到的模式的列,不要调用另一列的任何内容。如果某些内容在当前模式下未暴露,请告诉用户;不要切换传输方式。

OpenClaw 插件模式生成调用

await video_generate({
  model: "heygen/video_agent_v3",
  prompt: scriptWithFrameCheckNotes,
  aspectRatio: "16:9", // 或 "9:16"
  providerOptions: {
    avatar_id,
    voice_id,
    style_id,        // 可选
    callback_url,    // 可选异步 webhook
    callback_id,     // 可选关联 ID
  },
});

插件安装(一次性,由用户执行):openclaw plugins install clawhub:@heygen/openclaw-plugin-heygen。插件文档:https://github.com/heygen-com/openclaw-plugin-heygen。

MCP 工具名称(仅 MCP 模式)

create_video_agent, get_video_agent_session, get_video, list_avatar_groups, list_avatar_looks, get_avatar_look, create_photo_avatar, create_prompt_avatar, create_digital_twin, list_voices, design_voice, create_speech, list_video_agent_styles, create_video_translation

CLI 命令组(仅 CLI 模式)

heygen video-agent {create,get,send,stop,styles,resources,videos}, heygen video {get,list,download,delete}, heygen avatar {list,get,consent,create,looks} (带 heygen avatar looks {list,get,update}), heygen voice {list,create,speech}, heygen video-translate {create,get,languages}, heygen lipsync {create,get}, heygen asset create, heygen user me get, heygen auth {login,logout,status}。每个子命令都支持 --help — 这就是你的参考。运行 heygen --help 查看完整的名词列表。

不要查找 API 端点。 没有 api-reference.md 查找步骤。MCP 模式使用工具名称。CLI 模式使用 heygen ... --help。如果你发现自己正在搜索 REST 端点,请停止——你处于错误的心智模型中。

CLI 输出:stdout 上为 JSON,stderr 上为 {error:{code,message,hint}} 信封,退出码 0 正常 · 1 API · 2 用法 · 3 身份验证 · 4 超时。有关错误到操作映射和轮询节奏,请参阅 references/troubleshooting.md。在创建命令上添加 --wait 以阻塞直到完成,而不是手动处理轮询循环。


模式检测

信号模式起始于
模糊想法(“制作一个关于 X 的视频”)完整制作人发现
有书面提示增强提示提示制作
“直接生成” / 跳过问题快速拍摄生成
“交互式” / 与代理迭代交互式会话生成(实验性)

语言无关的路由: 这些信号描述的是用户的意图,而不是字面关键词。无论输入语言如何,都匹配意图。

快速拍摄头像规则: 如果不存在 AVATAR 文件,则省略 avatar_id 并让 Video Agent 自动选择。如果存在 AVATAR 文件,则使用它——并且画面检查仍然运行。

试运行模式: 如果用户说“试运行” / “预览”,则运行完整的流程,但在“生成”步骤呈现创意预览,而不是调用 API。

非英语视频: 相同的流程适用。脚本以视频语言编写。样式块、运动动词和画面检查更正保持英文。

默认情况下为完整制作人。提出一个有见地的问题比生成一个平庸的视频更好。


首次查看——首次运行头像检查

在会话中第一次视频请求之前,在“发现”步骤之前运行一次。

检查工作区根目录中是否存在任何 AVATAR-*.md 文件。目录还可能包含基于角色的符号链接(AVATAR-AGENT.md、AVATAR-USER.md),这些链接指向其中一个命名文件——这些由 heygen-avatar 阶段 5 维护,用于通用的自引用查找。扫描时,通过解析后的目标进行去重,这样同一个头像就不会被加载两次。

  • 找到: 读取文件,从 HeyGen 部分提取 Group ID 和 Voice ID。预加载为“发现”步骤的默认值。实际的 avatar_id(外观 ID)将在“画面检查”期间从 group_id 重新解析——切勿直接使用存储的 look_id。
  • 未找到: 用户(或代理)还没有头像。在继续创建视频之前,运行 heygen-avatar 技能来创建一个。告诉用户你会先设置他们的头像,以便在视频中保持一致的外观,并且大约需要一分钟。使用 user_language 沟通。在 heygen-avatar 完成并写入 AVATAR 文件后,返回到此处并使用新预加载的头像继续“发现”。
  • 头像就绪门控(阻塞): 加载头像后(无论是从现有的 AVATAR 文件还是新创建的),在使用它生成视频之前验证它是否就绪。调用 list_avatar_looks(group_id=<group_id>)(CLI:heygen avatar looks list --group-id <group_id>)并确认 preview_image_url 不为 null。如果为 null,则每 10 秒轮询一次,最多 5 分钟。在此检查通过之前,请勿继续“发现”。 提交未就绪头像的视频将静默失败。
  • 快速拍摄异常: 如果用户明确说“跳过头像” / “使用库存” / “直接生成”,则跳过此步骤并在没有头像的情况下继续进行。

简报检查(在“发现”之前运行)

检查工作区根目录下的 VIDEO-BRIEF-*.md(与 AVATAR-*.md 相同的查找模式)。 如果存在 status: locked 的文件:完全跳过“发现”和“脚本”。 直接获取Approved Script,从其 frontmatter 表中获取“发现”字段 (时长、方向、关键屏幕文本、视觉风格、资产、CTA),然后直接进入“提示制作”。 这是单次路径——heygen-brief 技能已经在自由聊天中完成了面试和脚本审批;不要重新询问其中的任何内容。 如果不存在简报文件,则按正常流程继续下面的“发现”。

发现

采访用户。要对话式,跳过已经回答的任何内容。

不要一次性批量提问所有这些内容。 一次只问一两个问题。大多数请求都带有可以推断的上下文(“30 秒创始人介绍”已经告诉了你时长 + 目的 + 语气)。只问那些真正缺少的内容。如果用户刚刚说“制作一个关于我的视频”,那么第一个正确的问题是目的——而不是一个 10 项的表单。

收集: (1) 目的, (2) 观众, (3) 时长, (4) 语气, (5) 分发(横屏/竖屏), (6) 资产, (7) 关键信息, (8) 视觉风格, (9) 头像, (10) 语言(从 user_language 自动检测;如果视频语言与聊天语言不同,请确认)。这将驱动语音选择(language 过滤器)、脚本语言和 voice_settings.locale。

资产

每个资产有两个路径:

  • 路径 A(情境化): 读取/分析,将信息烘焙到脚本中。适用于参考材料、需认证的内容。
  • **路径

Individual skills in this repo

This repo contains 9 individual skills — each has its own dedicated page.

Zuhair-01/claude-skills-and-systems

Create AI avatar videos with precise control over avatars, voices, scripts, scenes, and backgrounds using HeyGen's v2 API. Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Building multi-scene videos with different backgrounds per scene, (4) Creating transparent WebM videos for compositing, (5) Using talking photos as video presenters, (6) Integrating HeyGen avatars with Remotion, (7) Batch video generation with exact specs, (8) Brand-consistent production videos with precise control.

Zuhair-01/claude-skills-and-systems

Generate Mandarin and multilingual narration with Volcengine Doubao Speech 2.0. Use when creating Chinese voiceovers, when the user prefers Doubao/Volcengine/火山引擎/豆包 TTS, or when narration needs character-level timestamp metadata for subtitles.

Zuhair-01/claude-skills-and-systems

Edit existing videos using AI — remix style, upscale, remove background, and add audio via fal.ai's hosted video models.

Zuhair-01/claude-skills-and-systems

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Zuhair-01/claude-skills-and-systems

Author or edit a custom HyperFrames composition when no specialized workflow fits, or when BRIEF.md sets flow: companion. Use for longer or multi-scene pieces, brand and sizzle reels, montages, static loops, static title cards, footage remixes, and freeform builds. Use motion-graphics instead for a short unnarrated motion-first unit, including an animated title. Route fresh creation through hyperframes before using this skill.

Zuhair-01/claude-skills-and-systems

Read-only queue dashboard for workspace-aware ship. (gstack)

Zuhair-01/claude-skills-and-systems

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Zuhair-01/claude-skills-and-systems

The HyperFrames composition contract — build one renderable project. Use for composition structure, the `data-*` timing attributes, `class="clip"`, tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Zuhair-01/claude-skills-and-systems

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

相关技能