基于 awesome-codex-skills 与 Composio MCP 的 HeyGen AI 视频自动化生成实战指南【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills导读本文以仓库 composio-skills/heygen-automation/SKILL.md 为核心系统讲解如何通过 Codex Skill 与 Composio MCP 集成自动化完成 HeyGen 平台的 AI 视频生成全流程浏览模板与虚拟形象、按模板定制生成视频、轮询渲染状态并获取可分享链接。读完本文你将掌握一套可直接在 Codex CLI/API 中落地运行的 HeyGen 视频生产流水线并理解其底层工具调用契约与常见坑点规避策略。一、Skill 概览这条技能到底做什么heygen-automation是 awesome-codex-skills 仓库中一个典型的外部平台自动化型 Codex Skill。其SKILL.md的 frontmatter 明确定义了触发条件name: HeyGen Automation description: Automate AI video generation, avatar browsing, template-based video creation, and video status tracking through HeyGens platform via Composio requires: mcp: - rube按照仓库 README.md 对 Codex Skills 的说明每个 Skill 是独立的指令包Codex 依据description元数据决定何时触发该技能命中后才加载正文从而保持上下文精简。因此这条 Skill 的定位非常清晰——当用户需要批量生成 AI 视频、按模板定制数字人视频、跟踪视频渲染进度时自动激活。它的核心能力覆盖四条链路浏览拉取 HeyGen 官方模板库与虚拟形象Avatar库定制读取模板的完整变量结构将用户内容填入模板生成发起模板驱动的视频渲染任务跟踪与分发轮询处理状态、获取过期前可再生的视频 URL以及免登录的公开分享链接。所有这些操作都通过 Composio MCP 的HEYGEN_*工具集完成而非直接调用 HeyGen REST API——这是理解本文一切流程的前提。二、架构基础Codex Skill Composio MCPRube要正确使用这条 Skill需要先理解它的运行底座它由两层组成2.1 Codex Skills 层Skill 文件位于 composio-skills/heygen-automation/安装后 Codex 会把其中的指令当作执行手册指导 Agent 按顺序调用外部工具。仓库 README.md 中给出的技能目录标准布局为skill-name/ ├── SKILL.md # 必需指令 YAML frontmatter ├── scripts/ # 可选确定性操作的辅助脚本 ├── references/ # 可选仅在需要时加载的长文档 └── assets/ # 可选输出用模板或文件heygen-automation采用最精简形态仅一个SKILL.md把全部工作流、参数表与坑点收敛在单文件中符合 README 中避免在技能目录里堆额外文档以保持上下文精简的实践建议。2.2 Composio MCPRube层requires.mcp: [rube]声明了本技能依赖名为rube的 MCP 服务器。结合仓库 composio-skills/composio-automation/SKILL.md 的说明可以推断Rube MCP 是 Composio 提供的统一工具网关它为 1000 集成提供单一 MCP 端点内置认证、访问控制与审计能力见 README.md。Composio 的通用操作模式是用RUBE_SEARCH_TOOLS发现工具与最新 schema用RUBE_MANAGE_CONNECTIONS检查/建立目标应用的连接连接状态必须为ACTIVE用RUBE_MULTI_EXECUTE_TOOL按 schema 执行具体工具。而heygen-automation则直接聚焦于 HeyGen 这一个工具集把搜工具→连账号→执行的通用循环固化为 6 个HEYGEN_*工具的固定编排。三、环境准备与账号接入Setup在触发任何HEYGEN_*工具之前需要完成一次性的账号接入。原 Skill 文档给出了三个步骤接入 Composio MCP 服务器在 Codex 的客户端配置中将 MCP 服务器地址添加为https://rube.app/mcp。仓库中大量自动化 Skill如 elevenlabs、openai 等均声明同一端点说明这是 Composio 对外暴露的统一 MCP 网关地址完成 HeyGen 账号授权如果当前没有活跃连接Agent 会返回一个认证链接用户点击后以 OAuth 方式完成 HeyGen 账号与 Composio 的绑定。这一点与 composio-skills/composio-automation/SKILL.md 中连接非 ACTIVE 时跟随返回的 auth link 完成设置的约定一致确认工具可用连接成功后所有HEYGEN_*工具即可被 Agent 调用执行。接入状态自检建议在正式生成视频前先按 Composio 的通用模式检查连接状态——确认 HeyGen 工具集的连接处于ACTIVE否则后续所有调用都会因认证失败而报错。需要留意的是接入过程需要浏览器交互完成 OAuth属于一次性操作连接建立后会在 Composio 侧持久保存后续会话无需重复授权。四、核心工作流详解这是整条 Skill 的主体。六个工具按先侦察、后生成、再跟踪分发的逻辑编排下面逐个展开。4.1 浏览可用模板HEYGEN_V2_TEMPLATES用途从 HeyGen 模板库拉取预设计好的视频模板用于后续生成。工具HEYGEN_V2_TEMPLATES参数无参数。返回内容模板 ID、名称、预览图以及可定制选项的集合。实战要点这是生成视频前的第一步侦察动作。每个模板都有一个唯一 ID它是后续所有模板相关操作的输入主键。通过浏览返回的预览图与名称Agent 可以先筛选出与目标视频风格匹配的候选模板再进入下一步查看其内部结构。4.2 查看模板详情与变量HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3用途获取模板的完整结构包括全部变量、场景scene映射与定制选项。工具HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3参数类型必填说明template_idstring是来自HEYGEN_V2_TEMPLATES或 HeyGen 控制台的模板 ID关键定位这是生成视频不可跳过的前置步骤。它精确告诉你该模板需要填充哪些变量、每个变量的名称与类型。文档强调多场景multi-scene模板的变量结构往往相当复杂跳过此步直接生成极容易导致场景缺失或字段错配。实战要点将返回的变量清单完整记录下来作为下一步生成调用的输入字典字段名必须逐字符保持一致区分大小写与下划线。4.3 浏览可用虚拟形象HEYGEN_V2_AVATARS用途列出所有可用于视频制作的写实虚拟形象数字人便于为不同场景分配合适的角色。工具HEYGEN_V2_AVATARS参数无参数。返回内容虚拟形象标识符、名称与预览图。实战要点列表可能是分页返回的——即单次调用可能只返回一部分结果需要根据返回的分页标记追加调用才能拿到完整形象库。这在原文档的已知坑点中被专门标注Agent 在设计遍历逻辑时应主动处理分页。4.4 从模板生成视频HEYGEN_V2_TEMPLATE_GENERATE用途把用户的内容与变量填入模板发起视频渲染。工具HEYGEN_V2_TEMPLATE_GENERATE参数按原文档约定视频标题video title通过HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3发现的所有模板变量。硬性要求所有必填变量都必须提供且名称与类型必须与模板详情返回的结果完全一致——缺失或拼错的字段会导致场景渲染失败或整个生成任务报错。实战要点这一步是典型的结果取决于上游输入质量的操作。推荐的做法是先调用 4.2 获取变量 schema再逐项映射用户提供的内容最后用RUBE_SEARCH_TOOLS见 composio-skills/composio-automation/SKILL.md校验最新参数契约避免因 schema 变更导致硬编码参数失效。4.5 查询视频处理状态HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS用途轮询视频生成任务的进度并获取已完成视频的元数据与 URL。工具HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS参数类型必填说明video_idstring是生成接口返回的视频 IDURL 时效性返回的视频 URL 有效期7 天。过期后可以再次调用本接口重新生成新的有效 URL。实战要点视频渲染是异步任务——调用生成接口后并不能立即拿到成片。正确姿势是周期性轮询本接口直到状态变为完成complete后再使用输出的 URL绝不能拿渲染中的中间结果直接分发。轮询间隔建议依据视频长度设定避免过于频繁的空转调用。4.6 获取可分享的视频 URLHEYGEN_RETRIEVE_SHARABLE_VIDEO_URL用途生成一个公开的、无需登录即可观看的分享链接用于对外分发。工具HEYGEN_RETRIEVE_SHARABLE_VIDEO_URL参数video_id生成接口返回的视频 ID。实战要点这是分发环节的最后一步。与 4.5 返回的内部 URL 不同该接口产出的链接面向任何人可看的场景——适用于投放营销素材、发送给客户、嵌入外部页面等免登录访问需求。建议在视频渲染完成4.5 状态为完成后再调用。五、端到端流水线六步串成一条生产链路把上面六个工具按序串联就构成了一条完整的从想法到可分享成片的自动化流水线HEYGEN_V2_TEMPLATES │ ① 发现候选模板拿到 template_id ▼ HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3 │ ② 读取模板变量 schema必须 ▼ HEYGEN_V2_AVATARS可选 │ ③ 挑选/核对虚拟形象处理分页 ▼ HEYGEN_V2_TEMPLATE_GENERATE │ ④ 精确填入全部变量发起生成 ▼ HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS轮询 │ ⑤ 等待渲染完成取得 7 天有效 URL ▼ HEYGEN_RETRIEVE_SHARABLE_VIDEO_URL ⑥ 生成免登录公开分享链接这条流水线在 Codex 中表现为一次自然语言请求即可触发例如用 XX 模板为产品生成一条 30 秒的营销视频并给我一个可分享的链接——Agent 会按 Skill 的编排自动依次完成侦察、定制、生成、轮询与分发。仓库中其他自动化 Skill如 composio-skills/elevenlabs-automation/SKILL.md 的语音合成链路采用完全同构的浏览→详情→执行→跟踪模式可作为阅读本技能时的横向参考。六、已知坑点Known Pitfalls原文档将实战中最高频的失败模式整理成下表值得在编写自动化流程时逐条对照坑点详细说明模板变量必须全部提供HEYGEN_V2_TEMPLATE_GENERATE要求HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3返回的每一个变量都以精确的名称与类型提供——缺失或拼写错误的字段会破坏场景或直接导致生成失败必须先检查模板生成前绝不可跳过HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3——多场景模板的变量结构非常复杂视频 URL 会过期HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS返回的 URL 7 天后失效重新调用该接口即可再生成虚拟形象列表可能分页HEYGEN_V2_AVATARS可能返回分页结果——需要追加调用才能获取完整形象库处理时间不固定视频生成是异步任务必须轮询HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS直到状态为完成才能使用输出 URL对照仓库 composio-skills/composio-automation/SKILL.md 中列出的通用坑点工具 schema 会变化不要硬编码执行前确认连接 ACTIVE分页要取完可以发现heygen-automation的这五条坑点正是通用经验在 HeyGen 场景下的具体化schema 精确性、连接状态、分页、异步轮询是这类 Composio 自动化 Skill 共同的成败关键。七、快速参考Quick Reference以下速查表浓缩了本技能的全部工具面便于在对话中直接引用或作为 prompt 设计清单工具 Slug用途HEYGEN_V2_TEMPLATES列出可用视频模板HEYGEN_RETRIEVE_TEMPLATE_DETAILS_V3获取模板变量与场景结构HEYGEN_V2_AVATARS浏览可用 AI 虚拟形象HEYGEN_V2_TEMPLATE_GENERATE从模板生成视频HEYGEN_RETRIEVE_VIDEO_STATUS_DETAILS检查视频处理状态并获取 URLHEYGEN_RETRIEVE_SHARABLE_VIDEO_URL获取公开可分享的视频链接八、如何将本 Skill 安装到 Codex 环境要让 Codex 在实际会话中自动触发这条 HeyGen 技能需要先把heygen-automation安装到技能目录。依据 README.md 与 skill-installer/SKILL.md 的说明有两种方式方式一使用 Skill Installer推荐克隆仓库后用安装脚本将技能安装进$CODEX_HOME/skills默认~/.codex/skillspython skill-installer/scripts/install-skill-from-github.py \ --repo ComposioHQ/awesome-codex-skills \ --path composio-skills/heygen-automation安装脚本默认从公开 GitHub 仓库直接下载遇到认证/权限错误会自动回退到 git sparse checkout目标目录已存在时会中止避免覆盖。方式二手动复制将composio-skills/heygen-automation/目录整体复制到$CODEX_HOME/skills/下然后重启 Codex使其重新加载技能元数据。安装完成后验证ls ~/.codex/skills head ~/.codex/skills/heygen-automation/SKILL.md重启后在新会话中直接描述视频生成任务Codex 就会根据 frontmatter 的description匹配并加载本技能。注意本技能依赖rubeMCP 服务器安装技能后还需在 Codex 的 MCP 配置中接入https://rube.app/mcp并完成 HeyGen 账号授权见第三节技能才能真正跑通。结语heygen-automation是 awesome-codex-skills 仓库中平台自动化类技能的典型样本以一份精炼的SKILL.md把 HeyGen 的模板浏览、变量侦察、形象选择、视频生成、状态轮询与公开分发六个环节固化为可复用的执行契约。它的价值不仅在于能调 HeyGen 的接口更在于把异步渲染、URL 时效、分页与 schema 精确性这些真实生产约束显式写进了指令让 Codex Agent 可以开箱即用地跑通一条从文案到可分享成片的 AI 视频生产流水线。读者既可以将其直接部署到自己的 Codex 环境也可以把它作为编写其他 Composio 平台自动化 Skill 的范式参考。【免费下载链接】awesome-codex-skillsA curated list of practical Codex skills for automating workflows across the Codex CLI and API.项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-codex-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考