OpenMontage create-video 技能实战基于 HeyGen Video Agent 的文本直出视频全流程指南【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage本文是 OpenMontage 仓库中.claude/skills/create-video/SKILL.md及其九份参考文档的系统性解读面向希望用一句话生成完整视频的开发者与 AI Agent。文章完整继承技能文档中的 API 端点、请求参数、轮询与下载实现并结合仓库内 heygen_video.py 工具源码深入讲解从提示词工程、视觉风格编排到配额管理、Webhook 回调的生产级落地路径。一、技能定位什么是 create-videocreate-video是 OpenMontage 为 AI 编程助手Agent预置的一个 Claude Skill其核心能力是基于单个文本提示词prompt生成完整视频。与需要逐场景指定人物、声音、背景的传统视频生成 API 不同它背后的 HeyGen Video Agent 会自动接管以下环节脚本撰写script writing数字人形象选择avatar selection视觉画面visuals配音voiceover节奏把控pacing字幕生成captions技能的元数据frontmatter明确定义了它的适用触发场景见 .claude/skills/create-video/SKILL.md从一段描述或想法创建视频从提示词生成讲解、演示或营销视频不指定具体数字人、声音或场景时生成视频快速视频原型或草稿一次性的「提示词到视频」生成用户说给我做个视频或做一个关于 X 的视频。技能声明了allowed-tools: mcp__heygen__*即优先通过 HeyGen MCP 服务器暴露的工具完成调用并要求环境变量HEYGEN_API_KEY作为主凭据primaryEnv: HEYGEN_API_KEY。值得注意的是仓库的核心工具层同样内建了 HeyGen 支持heygen_video.py 中的HeyGenVideo工具声明了agent_skills [ai-video-gen, create-video]表明该 Skill 与仓库的 Agent 技能体系、工具注册表tool_registry.py是一体的其provider为heygen属于ToolTier.GENERATE层的云生成工具并内置fallback_tools回退链wan_video、hunyuan_video等本地/其他云方案这为 Skill 与仓库工具层互相印证提供了实现依据。二、认证与最小可用调用所有 HeyGen API 请求都需要在 HTTP 头中携带X-Api-Key。在本地环境设置环境变量后即可用 curl 发起一次最小请求curl -X POST https://api.heygen.com/v1/video_agent/generate \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d {prompt: Create a 60-second product demo video.}从仓库工具层可以印证这一凭据约定heygen_video.py 的install_instructions明确写有Set the HEYGEN_API_KEY environment variable其get_status()方法在检测到HEYGEN_API_KEY时返回ToolStatus.AVAILABLE否则返回UNAVAILABLE并以该环境变量作为能力开关。三、工具选择MCP 优先HTTP 兜底技能文档给出的核心原则是如果 HeyGen MCP 工具可用mcp__heygen__*优先使用它们——MCP 工具会自动处理认证与请求格式化否则退回直接 HTTP API 调用。任务MCP 工具兜底直接 API从提示词生成视频mcp__heygen__generate_video_agentPOST /v1/video_agent/generate查询视频状态 / 获取 URLmcp__heygen__get_videoGET /v2/videos/{video_id}列出账号下视频mcp__heygen__list_videosGET /v2/videos删除视频mcp__heygen__delete_videoDELETE /v2/videos/{video_id}在 OpenMontage 的仓库语境中这一先 MCP、后直连的分层策略与工具层的ExecutionMode.SYNC、ToolRuntime.API声明heygen_video.py相匹配Agent 既可以通过 MCP 通道在对话中直接生成也可以在流水线pipeline中以工具形式编排调用。四、Video Agent API 详解Video Agent API 与标准视频生成 API 的核心差异在于标准 API 需要逐场景配置video_inputs而 Video Agent 只需要一段提示词。以下是直接 API 的完整契约。4.1 请求端点与字段POST https://api.heygen.com/v1/video_agent/generate字段类型必填说明promptstring✓描述目标视频的文本提示词configobject配置项见下filesarray生成时引用的资产文件callback_idstring用于追踪的自定义 ID。设置时必须同时设置callback_url不需要 Webhook 时两者都应省略callback_urlstring完成通知的 Webhook URLConfig 对象字段类型说明duration_secinteger目标时长秒取值范围 5–300avatar_idstring指定使用的数字人可选未提供时由 Agent 自动选择orientationstringportrait或landscapeFiles 数组字段类型说明asset_idstring已上传资产的 ID上传方式见第八节响应格式{ error: null, data: { video_id: abc123 } }4.2 多语言调用示例curlcurl -X POST https://api.heygen.com/v1/video_agent/generate \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { prompt: Create a 60-second product demo video for a new AI-powered calendar app. The tone should be professional but friendly, targeting busy professionals. Highlight the smart scheduling feature and time zone handling. }Pythonimport requests import os from typing import Optional def generate_with_video_agent( prompt: str, duration_sec: Optional[int] None, avatar_id: Optional[str] None, orientation: Optional[str] None ) - str: request_body {prompt: prompt} config {} if duration_sec: config[duration_sec] duration_sec if avatar_id: config[avatar_id] avatar_id if orientation: config[orientation] orientation if config: request_body[config] config response requests.post( https://api.heygen.com/v1/video_agent/generate, headers{ X-Api-Key: os.environ[HEYGEN_API_KEY], Content-Type: application/json }, jsonrequest_body ) data response.json() if data.get(error): raise Exception(fVideo Agent failed: {data[error]}) return data[data][video_id]TypeScriptinterface VideoAgentConfig { duration_sec?: number; // 5-300 seconds avatar_id?: string; // Optional: specific avatar orientation?: portrait | landscape; } interface VideoAgentRequest { prompt: string; // Required config?: VideoAgentConfig; files?: { asset_id: string }[]; callback_id?: string; // Requires callback_url if set callback_url?: string; } async function generateWithVideoAgent( prompt: string, config?: VideoAgentConfig ): Promisestring { const request: VideoAgentRequest { prompt }; if (config) request.config config; const response await fetch( https://api.heygen.com/v1/video_agent/generate, { method: POST, headers: { X-Api-Key: process.env.HEYGEN_API_KEY!, Content-Type: application/json, }, body: JSON.stringify(request), } ); const json await response.json(); if (json.error) throw new Error(Video Agent failed: ${json.error}); return json.data.video_id; }4.3 常用配置组合场景配置仅提示词最简generateWithVideoAgent(Create a 30-second welcome video...)指定时长与方向{ duration_sec: 90, orientation: landscape }锁定数字人{ duration_sec: 120, avatar_id: josh_lite3_20230714, orientation: landscape }携带参考资产files: [{ asset_id: logoAssetId }, { asset_id: productImageId }]4.4 与标准 API 的对比与取舍使用场景推荐 API从想法快速出片Video Agent精确控制场景、数字人、节奏标准v2/video/generate规模化自动化内容生产Video Agent指定数字人与精确脚本标准v2/video/generate原型 / 草稿视频Video Agent品牌一致的成片生产标准v2/video/generate同一需求下Video Agent 只需一段描述等价的标准 API 请求则需要逐场景填写video_inputs包含character.avatar_id、voice.input_text、voice.voice_id、background.type与dimension等。Video Agent 的已知限制包括对最终脚本措辞控制较弱、未指定时数字人选择可能漂移、场景编排自动化、可能与严格品牌规范不一致、时长为近似值而非精确值。五、默认工作流生成 → 轮询 → 下载5.1 标准三步流程使用 MCP 工具时用提示词优化器见第六节写出优化后的 prompt调用mcp__heygen__generate_video_agent传入 prompt 与配置duration_sec、orientation、avatar_id用返回的video_id调用mcp__heygen__get_video轮询状态并获取下载 URL。无 MCP直连 API时写出优化后的 promptPOST /v1/video_agent/generateGET /v2/videos/id查询状态。5.2 状态查询curl -X GET https://api.heygen.com/v2/videos/YOUR_VIDEO_ID \ -H X-Api-Key: $HEYGEN_API_KEY状态类型状态说明pending视频已进入处理队列processing正在生成completed可下载failed生成失败完成与失败的响应示例{ error: null, data: { id: abc123, status: completed, video_url: https://files.heygen.ai/video/abc123.mp4, thumbnail_url: https://files.heygen.ai/thumbnail/abc123.jpg, duration: 45.2, title: My Video, created_at: 2024-01-15T10:30:00Z, completed_at: 2024-01-15T10:38:00Z, gif_url: https://files.heygen.ai/gif/abc123.gif, captioned_video_url: null, subtitle_url: null, folder_id: null, output_language: en } }{ error: null, data: { id: abc123, status: failed, failure_code: script_too_long, failure_message: Script too long for selected avatar } }5.3 生成时长预期视频生成通常需要5–15 分钟高峰负载或脚本较长时可能超过 20 分钟。影响因子包括脚本长度越长越久、分辨率1080p 慢于 720p、数字人复杂度、队列负载、场景数量。官方建议超时设置为15–20 分钟900,000–1,200,000 ms配音脚本超过 2 分钟时预期等待 15 分钟以上长视频考虑异步模式先保存video_id稍后再查。5.4 Python 轮询实现import time from typing import Optional, Callable def wait_for_video( video_id: str, max_wait_seconds: int 600, poll_interval: int 5, on_progress: Optional[Callable[[str, int], None]] None ) - str: start_time time.time() while time.time() - start_time max_wait_seconds: elapsed int(time.time() - start_time) status_data get_video_status(video_id) status status_data[status] if on_progress: on_progress(status, elapsed) if status completed: return status_data[video_url] elif status failed: raise Exception(status_data.get(failure_message, Video generation failed)) time.sleep(poll_interval) raise Exception(Video generation timed out)5.5 下载与重试重要提醒状态显示completed后下载 URL 可能不会立即可用需要带退避的重试逻辑。Python 实现import requests import time def download_video_with_retry( video_url: str, output_path: str, max_retries: int 5, initial_delay: float 2.0 ) - None: last_error None for attempt in range(max_retries): try: response requests.get(video_url, streamTrue, timeout60) response.raise_for_status() with open(output_path, wb) as f: for chunk in response.iter_content(chunk_size8192): f.write(chunk) print(fVideo downloaded to {output_path}) return except Exception as e: last_error e delay initial_delay * (2 ** attempt) # 指数退避 print(fDownload attempt {attempt 1} failed, retrying in {delay}s...) time.sleep(delay) raise Exception(fFailed to download after {max_retries} attempts: {last_error})5.6 可恢复的状态检查模式对于长耗时生成不必让进程一直挂起轮询。推荐先生成、后查询的 CLI 模式调用生成接口把{videoId, createdAt, script, avatarId, voiceId}写入pending-video.json后立即退出进程之后运行check-status.ts支持--wait参数单次检查或持续等待完成时把结果video_url、duration、thumbnail_url等落盘为video-result.json并清理 pending 文件失败时打印failure_message并清理 pending 文件。六、提示词优化方法论从 Brief 到生产级 Prompt技能的文档体系反复强调同一句话平庸与专业结果的差距完全取决于提示词质量。prompt-optimizer.md基于 40 部实际产出视频的经验沉淀其最核心的洞察是Video Agent 本质是一个 HTML 解释器——它能原生渲染版式、字体排印与结构化内容。因此描述 B-roll 时要用动作动词slams in、types on、counts up来刻画分层文字动效而不是给布局规格左上角、48pt。6.1 Brief to Prompt 十步工作流Pull data收集数据——通过网络搜索、API、内部文档研究主题收集真实引用、数据、社交账号Synthesize a thesis综合论点——不是清单而是故事X 之所以发生是因为 Y——以下是证据。归并为 3–5 个主题构成叙事弧线Choose a style选风格——先匹配情绪、后匹配内容问观众应该有什么感受20 种风格见第七节Write the avatar写数字人——主题化着装匹配内容情感语境场景内置品牌 Logo 与内容相关道具见 6.3Extract critical text提取关键文本——列出所有必须原样出现的数字、引用、账号、标签Break into scenes拆场景——一个场景一个概念轮换场景类型同类型连续不超过 3 个至少 2 个纯 B-roll 场景Write voiceover写配音——配音里把数字拼读出来one-point-eight-five million屏幕上用数字1.85M每个场景含 B-roll都要有旁白Layer each B-roll scene分层 B-roll——L1 背景、L2 主角、L3 支撑、L4 信息条、L5 特效每个元素都必须动起来Add music direction加音乐方向——引用参考艺术家描述能量弧线Add narration style加旁白风格——语速快慢、停顿位置、各段落情绪基调。6.2 Prompt Anatomy生产级提示词的八大区块FORMAT: What kind of video, how long, what energy TONE: Emotional register, references AVATAR: Detailed physical environment description (60-100 words) STYLE: Named aesthetic with colors, typography, motion rules, transitions CRITICAL ON-SCREEN TEXT: Exact strings that must appear SCENE-BY-SCENE: Individual scene breakdowns with VO and layered visuals MUSIC: Genre, reference artists, energy arc NARRATION STYLE: How to deliver the voiceoverFORMAT 示例FORMAT: 75-second high-energy tech daily briefing. Think: a creator who just got amazing news. FORMAT: Bloomberg-style strategy briefing. 100-120 seconds. CEO-delivered.TONE 示例TONE: Confident, direct,>论点驱动——是故事而非要点列表风格已命名并含颜色、字体、动效、转场数字人有主题化着装 品牌化环境60–100 词关键文本全部列出——每个数据、引用、标签场景类型轮换——同类型不超过 3 个至少 2 个 B-roll每个场景都有 VOICEOVER——包括 B-rollB-roll 场景 4 层每个元素都有动作动词B-roll 场景 10–15 秒绝不 ≤5s提及公司时出现品牌 Logo每个元素都在动——无静态帧七、20 种视觉风格库visual-styles.md提供 20 种以真实设计师为灵感的命名风格按情绪强度排序。选风格先匹配情绪、后匹配内容使用时把风格块复制进提示词的STYLE区只使用其视觉语言规则不要注入示例 B-roll 场景。7.1 速查表#风格设计师情绪最佳场景1Soft SignalSagmeister亲密、温暖个人故事、健康2Warm GrainEksell有机、友好环境、可持续3Quiet DramaRay人文、沉思人物志、传记4Heritage ReelCassandre怀旧、复古历史、回顾5Silk RouteAbedini流动、神秘全球事务、跨文化6Swiss PulseMüller-Brockmann临床、精确数据密集、分析7Geometric BoldTanaka极简、优雅生活方式、视觉散文8Velvet StandardVignelli高级、永恒奢侈品、投资人更新9Digital GridCrouwel系统、技术基建、工程10Contact SheetBrodovitch编辑、调查新闻、深度报道11Folk FrequencyTerrazas文化、生动节日、美食、遗产12Earth PulseGhariokwu接地、社群社区、草根13Dream StateTomaszewski超现实、诗意评论、哲学14Play ModeAhn Sang-soo俏皮、不羁娱乐、流行文化15Carnival SurgeLins亢奋、庆祝里程碑、炒作16Shadow CutHillmann黑暗、电影感曝光、调查17DeconstructedBrody工业、粗粝科技新闻、朋克能量18Maximalist TypeScher大声、动态大公告、发布19Data DriftAnadol未来、沉浸AI/科技、创新20Red WireTartakover紧迫、即时突发新闻、危机7.2 情绪到风格的映射内容感觉使用个人、亲密Soft Signal、Quiet Drama自然、泥土感Warm Grain、Earth Pulse怀旧、历史Heritage Reel数据驱动、分析Swiss Pulse、Digital Grid优雅、高级Velvet Standard、Geometric Bold文化、全球化Silk Route、Folk Frequency调查、严肃Contact Sheet、Shadow Cut有趣、轻松Play Mode、Carnival Surge哲学、抽象Dream State朋克、草根、粗粝Deconstructed炒作、大声、高能量Maximalist Type科技前瞻、未来Data Drift突发、紧迫Red Wire7.3 三种代表性风格完整规格Swiss PulseMüller-Brockmann——数据与分析首选STYLE — SWISS PULSE (Müller-Brockmann): Black/white electric blue #0066FF. Grid-locked. Helvetica Bold. Animated counters. Diagonal accents. Grid wipe transitions.细节黑#1a1a1a、白、单一强调色电光蓝#0066FFHelvetica Bold 标题 / Regular 标签数字放大到 80–120pt所有元素对齐 12 列网格计数器从 0 累加关键节点用对角构图Grid wipe 与硬切不用溶解。DeconstructedBrody——科技新闻与朋克能量STYLE — DECONSTRUCTED (Brody): Dark grey #1a1a1a, rust orange #D4501E. Type at angles, overlapping. Gritty textures, scan-line glitch. Smash cuts with flash frames.细节深灰#1a1a1a、黑、锈橙#D4501E、生白#f0f0f0文字倾斜、重叠、溢出边框高对比粗粝纹理刮痕金属、剥落油漆、扫描线故障文字 SLAMS / SHATTERS / PUNCHES字母打乱后回正。Digital GridCrouwel——基础设施与工程STYLE — DIGITAL GRID (Crouwel): Monospaced type. Dark #0a0a0a with cyan #00E5FF, amber #FFB300. Pixel grid overlays. Terminal aesthetic. Clean wipe transitions.细节深黑#0a0a0a 青色#00E5FF、琥珀#FFB300、绿#00FF88全等宽字体代码终端美学像素网格叠加可见网格节点依次点亮扫描线效果与光标闪烁。7.4 自定义风格配方风格是可组合的。自定义风格的通用模式命名风格 设计师参考 调色板 字体排印 运动规则 转场。例如 Velvet StandardVignelli黑、白、单一浓郁强调色深海军蓝#1a237e或金#c9a84c细无衬线全大写宽字距大量负空间对称居中、建筑式精确慢速序列揭示优雅交叉溶解。八、参考资产上传与使用Video Agent 支持引用自定义资产图片、视频、音频来理解你的品牌与产品。上传是单步流程直接把文件二进制 POST 到上传端点Content-Type必须与文件 MIME 类型一致。端点POST https://upload.heygen.com/v1/assetcurl -X POST https://upload.heygen.com/v1/asset \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: image/jpeg \ --data-binary ./background.jpg响应字段code100表示成功、data.id资产 ID用于生成时引用、data.name、data.file_typeimage/video/audio、data.url、data.image_key仅图片用于创建照片数字人、data.folder_id、data.meta、data.created_ts。支持的 Content-TypeJPEGimage/jpeg、PNGimage/png、MP4video/mp4、WebMvideo/webm、MP3audio/mpeg、WAVaudio/wav。资产限制文件最大 10MB图片尺寸建议与视频尺寸一致音频时长应与目标视频长度匹配资产在一段非活跃期后可能被删除。使用方式标准 API 语境上传返回的url可作为背景图background: { type: image, url }图片资产的id可作为说话照片数字人talking_photo_id音频资产的url可作为配音voice: { type: audio, audio_url }。上传前应本地校验类型与大小对失败上传实现重试并缓存资产 ID以便跨多次视频生成复用。九、尺寸、分辨率与配额管理9.1 分辨率与平台推荐比例720p1080p典型平台16:9 横屏1280×7201920×1080YouTube、LinkedIn9:16 竖屏720×12801080×1920TikTok、Reels、Shorts1:1 方形720×7201080×1080Instagram 信息流自定义尺寸约束任意边最小 128px、最大 4096px、宽高必须为偶数。分辨率与积分成本挂钩1080p 约为 720p 的 1.5 倍因此草稿与测试阶段建议 720p终稿再升 1080p。9.2 配额检查curl -X GET https://api.heygen.com/v2/user/remaining_quota \ -H X-Api-Key: $HEYGEN_API_KEY{ error: null, data: { remaining_quota: 450, used_quota: 50 } }积分消耗参考标准视频约 1 积分/分钟720p 为基础费率1080p 约 1.5 倍视频翻译按长度计费流式数字人按会话计费。最佳实践生成前先做配额预检估算所需积分并与remaining_quota比较定期记录percentUsed设置低配额告警阈值如低于 50开发期优先使用测试模式避免消耗积分。十、Webhook替代轮询的生产方案对生产系统而言Webhook 比轮询更高效——HeyGen 会在视频完成、失败、翻译完成、数字人训练完成等异步操作结束时主动推送通知。10.1 事件类型事件类型说明avatar_video.success视频生成完成avatar_video.fail视频生成失败video_translate.success翻译完成video_translate.fail翻译失败instant_avatar.success即时数字人创建完成instant_avatar.fail即时数字人创建失败10.2 事件负载成功事件{ event_type: avatar_video.success, event_data: { video_id: abc123, video_url: https://files.heygen.ai/video/abc123.mp4, thumbnail_url: https://files.heygen.ai/thumbnail/abc123.jpg, duration: 45.2, callback_id: your_custom_id } }失败事件{ event_type: avatar_video.fail, event_data: { video_id: abc123, error: Script too long for selected avatar, callback_id: your_custom_id } }10.3 注册与回调 ID注册端点POST https://api.heygen.com/v1/webhook/endpoint.add字段url必填、events必填订阅的事件数组、secret可选签名校验用共享密钥。curl -X POST https://api.heygen.com/v1/webhook/endpoint.add \ -H X-Api-Key: $HEYGEN_API_KEY \ -H Content-Type: application/json \ -d { url: https://your-domain.com/webhook/heygen, events: [avatar_video.success, avatar_video.fail] }生成时携带callback_id须同时设置callback_url即可在回调中把event_data.callback_id映射回原始业务请求如订单号。10.4 安全与可靠性要点端点应在 5 秒内返回 200事件异步处理用 HMAC-SHA256 校验签名x-heygen-signature头防止伪造事件同一事件可能多次投递需做幂等处理实现重试与失败事件落库本地开发可用 ngrok 暴露隧道测试。Webhook vs 轮询对比维度Webhook轮询延迟即时取决于轮询间隔效率高推送低重复请求复杂度需要端点实现更简单可靠性需自建重试保证可达成本API 用量低API 用量高十一、技能选择create-video vs avatar-video仓库中还提供了avatar-video技能见 .claude/skills/avatar-video/SKILL.md。两者的边界是create-video 面向描述即视频的提示词驱动创作当用户需要精确控制具体数字人、精确脚本、逐场景的声音/背景配置或复杂多场景合成时应改用 avatar-video。用户诉求create-videoavatar-video给我做一个关于 X 的视频✓做一个产品演示✓我要数字人 Y 精确说出 Z✓不同背景的多场景视频✓透明 WebM 用于合成✓十二、完整实战示例Brief 到成片参考 prompt-examples.md 中的完整案例输入 Brief 与输出 Prompt 的结构如下。输入 BriefTopic: Monthly company report for a SaaS startup Key data: $141M ARR (up from $54M), 1.85M signups (28%), 3M paid videos/month Customer story: Creator built AI character, 2.5M followers, 20 min/video Challenge: Organic traffic volatile, -16% last week Duration: ~90 seconds Tone: Confident CEO, contenteditable="false">【免费下载链接】OpenMontageWorlds first open-source, agentic video production system. 12 production pipelines, 100 tools, 700 agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考