企业官网建设流程全解析

OpenMontage create-video 技能实战：基于 HeyGen Video Agent 的文本直出视频全流程指南

【免费下载链接】OpenMontageWorld's 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-video

create-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）：

1. 从一段描述或想法创建视频；
2. 从提示词生成讲解、演示或营销视频；
3. 不指定具体数字人、声音或场景时生成视频；
4. 快速视频原型或草稿；
5. 一次性的「提示词到视频」生成；
6. 用户说"给我做个视频"或"做一个关于 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 调用。

在 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

Config 对象：

Files 数组：

响应格式：

{ "error": null, "data": { "video_id": "abc123" } }

4.2 多语言调用示例

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 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." }'

Python：

import 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" }, json=request_body ) data = response.json() if data.get("error"): raise Exception(f"Video Agent failed: {data['error']}") return data["data"]["video_id"]

TypeScript：

interface 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 ): Promise<string> { 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 常用配置组合

4.4 与标准 API 的对比与取舍

同一需求下，Video Agent 只需一段描述；等价的标准 API 请求则需要逐场景填写video_inputs（包含character.avatar_id、voice.input_text、voice.voice_id、background.type与dimension等）。Video Agent 的已知限制包括：对最终脚本措辞控制较弱、未指定时数字人选择可能漂移、场景编排自动化、可能与严格品牌规范不一致、时长为近似值而非精确值。

五、默认工作流：生成 → 轮询 → 下载

5.1 标准三步流程

使用 MCP 工具时：

1. 用提示词优化器（见第六节）写出优化后的 prompt；
2. 调用mcp__heygen__generate_video_agent，传入 prompt 与配置（duration_sec、orientation、avatar_id）；
3. 用返回的video_id调用mcp__heygen__get_video轮询状态并获取下载 URL。

无 MCP（直连 API）时：

1. 写出优化后的 prompt；
2. POST /v1/video_agent/generate；
3. GET /v2/videos/<id>查询状态。

5.2 状态查询

curl -X GET "https://api.heygen.com/v2/videos/YOUR_VIDEO_ID" \ -H "X-Api-Key: $HEYGEN_API_KEY"

状态类型：

完成与失败的响应示例：

{ "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, stream=True, timeout=60) response.raise_for_status() with open(output_path, "wb") as f: for chunk in response.iter_content(chunk_size=8192): f.write(chunk) print(f"Video downloaded to {output_path}") return except Exception as e: last_error = e delay = initial_delay * (2 ** attempt) # 指数退避 print(f"Download attempt {attempt + 1} failed, retrying in {delay}s...") time.sleep(delay) raise Exception(f"Failed to download after {max_retries} attempts: {last_error}")

5.6 可恢复的状态检查模式

对于长耗时生成，不必让进程一直挂起轮询。推荐"先生成、后查询"的 CLI 模式：

1. 调用生成接口，把{videoId, createdAt, script, avatarId, voiceId}写入pending-video.json后立即退出进程；
2. 之后运行check-status.ts（支持--wait参数）单次检查或持续等待；
3. 完成时把结果（video_url、duration、thumbnail_url等）落盘为video-result.json并清理 pending 文件；
4. 失败时打印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 十步工作流

1. Pull data（收集数据）——通过网络搜索、API、内部文档研究主题，收集真实引用、数据、社交账号；
2. Synthesize a thesis（综合论点）——不是清单而是故事："X 之所以发生是因为 Y——以下是证据"。归并为 3–5 个主题，构成叙事弧线；
3. Choose a style（选风格）——先匹配情绪、后匹配内容，问"观众应该有什么感受？"（20 种风格见第七节）；
4. Write the avatar（写数字人）——主题化着装，匹配内容情感语境；场景内置品牌 Logo 与内容相关道具（见 6.3）；
5. Extract critical text（提取关键文本）——列出所有必须原样出现的数字、引用、账号、标签；
6. Break into scenes（拆场景）——一个场景一个概念；轮换场景类型，同类型连续不超过 3 个；至少 2 个纯 B-roll 场景；
7. Write voiceover（写配音）——配音里把数字拼读出来（"one-point-eight-five million"），屏幕上用数字（"1.85M"）；每个场景（含 B-roll）都要有旁白；
8. Layer each B-roll scene（分层 B-roll）——L1 背景、L2 主角、L3 支撑、L4 信息条、L5 特效，每个元素都必须动起来；
9. Add music direction（加音乐方向）——引用参考艺术家，描述能量弧线；
10. 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 voiceover

FORMAT 示例：

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-roll
B-roll 场景 4+ 层，每个元素都有动作动词
B-roll 场景 10–15 秒（绝不 ≤5s）
提及公司时出现品牌 Logo
每个元素都在动——无静态帧
七、20 种视觉风格库
visual-styles.md提供 20 种以真实设计师为灵感的命名风格，按情绪强度排序。选风格先匹配情绪、后匹配内容；使用时把风格块复制进提示词的STYLE区，只使用其视觉语言规则，不要注入示例 B-roll 场景。
7.1 速查表
#
风格
设计师
情绪
最佳场景
1
Soft Signal
Sagmeister
亲密、温暖
个人故事、健康
2
Warm Grain
Eksell
有机、友好
环境、可持续
3
Quiet Drama
Ray
人文、沉思
人物志、传记
4
Heritage Reel
Cassandre
怀旧、复古
历史、回顾
5
Silk Route
Abedini
流动、神秘
全球事务、跨文化
6
Swiss Pulse
Müller-Brockmann
临床、精确
数据密集、分析
7
Geometric Bold
Tanaka
极简、优雅
生活方式、视觉散文
8
Velvet Standard
Vignelli
高级、永恒
奢侈品、投资人更新
9
Digital Grid
Crouwel
系统、技术
基建、工程
10
Contact Sheet
Brodovitch
编辑、调查
新闻、深度报道
11
Folk Frequency
Terrazas
文化、生动
节日、美食、遗产
12
Earth Pulse
Ghariokwu
接地、社群
社区、草根
13
Dream State
Tomaszewski
超现实、诗意
评论、哲学
14
Play Mode
Ahn Sang-soo
俏皮、不羁
娱乐、流行文化
15
Carnival Surge
Lins
亢奋、庆祝
里程碑、炒作
16
Shadow Cut
Hillmann
黑暗、电影感
曝光、调查
17
Deconstructed
Brody
工业、粗粝
科技新闻、朋克能量
18
Maximalist Type
Scher
大声、动态
大公告、发布
19
Data Drift
Anadol
未来、沉浸
AI/科技、创新
20
Red Wire
Tartakover
紧迫、即时
突发新闻、危机
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 Wire
7.3 三种代表性风格完整规格
Swiss Pulse（Mü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、白、单一强调色电光蓝#0066FF；Helvetica Bold 标题 / Regular 标签；数字放大到 80–120pt；所有元素对齐 12 列网格；计数器从 0 累加；关键节点用对角构图；Grid wipe 与硬切，不用溶解。
Deconstructed（Brody）——科技新闻与朋克能量：
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 Grid（Crouwel）——基础设施与工程：
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 Standard（Vignelli）：黑、白、单一浓郁强调色（深海军蓝#1a237e或金#c9a84c），细无衬线全大写宽字距，大量负空间，对称居中、建筑式精确，慢速序列揭示，优雅交叉溶解。
八、参考资产上传与使用
Video Agent 支持引用自定义资产（图片、视频、音频）来理解你的品牌与产品。上传是单步流程：直接把文件二进制 POST 到上传端点，Content-Type必须与文件 MIME 类型一致。
端点：POST https://upload.heygen.com/v1/asset
curl -X POST "https://upload.heygen.com/v1/asset" \ -H "X-Api-Key: $HEYGEN_API_KEY" \ -H "Content-Type: image/jpeg" \ --data-binary '@./background.jpg'
响应字段：code（100表示成功）、data.id（资产 ID，用于生成时引用）、data.name、data.file_type（image/video/audio）、data.url、data.image_key（仅图片，用于创建照片数字人）、data.folder_id、data.meta、data.created_ts。
支持的 Content-Type：JPEGimage/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 分辨率与平台推荐
比例
720p
1080p
典型平台
16:9 横屏
1280×720
1920×1080
YouTube、LinkedIn
9:16 竖屏
720×1280
1080×1920
TikTok、Reels、Shorts
1:1 方形
720×720
1080×1080
Instagram 信息流
自定义尺寸约束：任意边最小 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-video
avatar-video
"给我做一个关于 X 的视频"
✓
"做一个产品演示"
✓
"我要数字人 Y 精确说出 Z"
✓
"不同背景的多场景视频"
✓
"透明 WebM 用于合成"
✓
十二、完整实战示例：Brief 到成片
参考 prompt-examples.md 中的完整案例，输入 Brief 与输出 Prompt 的结构如下。
输入 Brief：
Topic: 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">【免费下载链接】OpenMontageWorld's 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