OpenMontage HeyGen Video Agent 提示词生产示例与可复用模板解析-开发者社区

OpenMontage 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 的 Agent 技能体系中，HeyGen Video Agent 负责"一句话生成完整视频"，而决定成片质量上限的正是提示词本身。本文以 .agents/skills/heygen/references/prompt-examples.md 为主体，完整拆解其"从需求简报（Brief）到生产级提示词"的标杆示例，并继承全部 5 个即用模板（Tech News Briefing、Product Comparison、Strategy Presentation、Social Ad、Premium Report），结合仓库中的 prompt-optimizer.md、visual-styles.md 与 API 参考文档 video-agent.md，讲清楚这些提示词如何被结构化、如何发送到 Video Agent API，以及为什么这样写。读完后你能够把任意业务简报改写为可直接投喂给 Video Agent 的逐场景提示词，并掌握其分层视觉（L1–L5）与运动动词体系的底层逻辑。

1. 文档定位：它在技能体系中的角色

prompt-examples.md 是 HeyGen 技能包（skill）的参考文件之一。heygen 技能入口将其定位为 "Full production prompt example + ready-to-use templates"（完整生产级提示词示例 + 即用模板），与 prompt-optimizer.md 的写作规则、visual-styles.md 的 20 种命名视觉样式共同构成"写提示词"的知识链。

需要注意仓库当前的技能演进状态：heygen SKILL.md 标注该技能已废弃（DEPRECATED），建议改用两个更聚焦的技能：

create-video—— 基于提示词调用 Video Agent 生成视频，其 SKILL.md 仍然引用同一组参考文件（prompt-optimizer → visual-styles → prompt-examples → video-agent）；
avatar-video—— 需要精确控制特定头像、语音、逐场景脚本时使用。

因此本文内容对应的是 Video Agent（POST /v1/video_agent/generate）这条"提示词驱动"路径。create-video 技能的最佳实践第一条即明确："结果与平庸之间的差距完全取决于提示词质量"，这正是 prompt-examples 文档存在的意义。

2. 标杆示例：从月度简报到 90 秒 Bloomberg 风格提示词

文档的第一部分是一个完整的 Brief → Prompt 转换示例。理解这个示例，就理解了本文档的全部方法论。

2.1 输入简报（Input 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,>必填说明promptstring✓本文第 2、3 节产出的提示词全文configobjectduration_sec（5–300 秒）、avatar_id（省略则由 Agent 选择）、orientation（"portrait"/"landscape"）filesarray已上传资产的asset_id列表，可让 Agent 参考品牌 Logo、产品截图callback_id/callback_urlstringWebhook 回调，二者需同时提供或同时省略最小可用请求（video-agent.md 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": "<本文第 2 节或第 3 节产出的完整提示词>" }'
返回data.video_id后，用GET /v2/videos/{video_id}轮询状态并取下载 URL（video-status.md）。如果环境里连接了 HeyGen MCP 服务器，则优先用mcp__heygen__generate_video_agent/mcp__heygen__get_video替代裸 HTTP（create-video 工具选择表）。
两个与模板字段直接对应的工程细节：
Social Ad 模板的 "Portrait 9:16" 对应config.orientation: "portrait"；各模板的 30/60/75/90/120 秒分别落在duration_sec（5–300）的取值范围内；
标杆示例中"COMPANY NAME"这类品牌元素，实操上可先把 Logo 上传为资产再通过files传入，video-agent.md 的 With Reference Files 示例 展示了该流程。
同时 video-agent.md 的 Limitations 提醒：脚本措辞不完全可控、未锁定avatar_id时头像可能漂移、时长是近似值——这些正是需要"逐字文本"和"精确品牌规范"时应改用标准 v2 场景化 API（avatar-video技能）的原因。
5. 仓库源码侧的印证：heygen_video 工具与技能联动
从 OpenMontage 的工具注册层看，tools/video/heygen_video.py 定义了HeyGenVideo工具，可以印证本文文档在仓库中的实际落地方式：
鉴权与可用性：get_status 以HEYGEN_API_KEY环境变量是否存在决定工具是否可用，与技能包 metadata 中声明的 primaryEnv 一致；
技能联动：agent_skills 字段 声明为["ai-video-gen", "create-video"]，即调用该工具时 Agent 会加载 create-video 技能包——而 create-video 技能引用的正是本文拆解的 prompt-examples.md 这一参考文件（create-video SKILL.md 引用列表）。从源码结构看，"工具负责执行、技能文件负责教会 Agent 写出高质量 prompt" 的分工，就是这套示例文档能被真实生产流程消费的路径；
失败兜底：fallback_tools 列出了 wan_video、hunyuan_video 等本地/其他云端生成器，提示 HeyGen 路径属于ToolStability.EXPERIMENTAL、需网络的云端生成（supports 声明），使用时应把 API Key 与额度（quota.md）纳入预算考量。
需要说明：heygen_video工具的input_schema目前只接收prompt+ provider_variant（veo/sora/kling 等）这类"通用文生视频"参数，而本文的逐场景结构化提示词是面向 Video Agent 端点设计的；两者共用HEYGEN_API_KEY，但 video-agent.md 描述的/v1/video_agent/generate端点是提示词驱动的独立入口，这也是技能文档将其作为"首选路径"（"Prefer Video Agent for most video requests"）的原因。
6. 实践要点清单
把本文方法压缩为可执行步骤：
Brief 先行：像 2.1 节那样先整理主题、数据、故事、挑战、时长、语气六要素，不要把原始素材直接投给 API；
按 8 段式展开：FORMAT → TONE → AVATAR → STYLE → CRITICAL ON-SCREEN TEXT → 逐场景 → MUSIC → NARRATION STYLE，每段都有 prompt-optimizer 的写法约束；
选样式先问情绪："观众应该感受到什么？" 再用 Mood-to-Style Guide 映射到 20 种命名样式，只抄样式规则、不抄示例场景；
场景纪律：类型轮换、每场 VO、B-roll 10–15s 且 ≥4 层、每个元素带动词；数字在口播稿里拼读、在屏幕文本里用数字；
从 5 个模板起步：按内容场景选 3.1–3.5 的骨架，替换方括号占位符，过一遍 Quality Checklist；
发送与验证：POST /v1/video_agent/generate（提示词全文入prompt，模板时长入duration_sec，竖版广告设orientation: "portrait"，品牌素材走files），轮询GET /v2/videos/{id}取片；
迭代：Video Agent 的时长与措辞是近似的，把它当快速迭代通道，最终品牌级交付再考虑 v2 场景化 API。
7. 延伸阅读（仓库内路径）
prompt-examples.md —— 本文主体：完整生产示例 + 5 个模板
prompt-optimizer.md —— 提示词写法的核心规则、分层系统、运动词汇、实测数据
visual-styles.md —— 20 种命名视觉样式完整规格
video-agent.md —— Video Agent API 端点、字段、curl/TS/Python 示例
video-status.md / quota.md / dimensions.md —— 轮询、额度、分辨率
heygen SKILL.md（已废弃）与 create-video SKILL.md —— 技能入口与工具选择
tools/video/heygen_video.py —— 仓库内 HeyGen 云端视频工具的注册与兜底逻辑
【免费下载链接】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