create-video

创建视频

根据文本提示词生成完整视频。描述你想要的内容，AI 会自动处理脚本编写、头像选择、视觉效果、配音、节奏和字幕。

身份验证

所有请求都需要 X-Api-Key 标头。设置 HEYGEN_API_KEY 环境变量。

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 MCP 工具（mcp__heygen__*）可用，优先使用它们，而不是直接调用 HTTP API——它们会自动处理身份验证和请求格式。

任务	MCP 工具	备用方案（直接 API）
根据提示词生成视频	mcp__heygen__generate_video_agent	POST /v1/video_agent/generate
检查视频状态 / 获取 URL	mcp__heygen__get_video	GET /v2/videos/{video_id}
列出账户视频	mcp__heygen__list_videos	GET /v2/videos
删除视频	mcp__heygen__delete_video	DELETE /v2/videos/{video_id}

如果没有 HeyGen MCP 工具可用，请按照参考文件中的说明直接调用 HTTP API。

默认工作流

始终按照 prompt-optimizer.md 中的指南，使用场景、时间安排和视觉风格来组织提示词。

使用 MCP 工具：

1. 按照 prompt-optimizer.md → visual-styles.md 编写优化后的提示词
2. 使用提示词和配置（duration_sec、orientation、avatar_id）调用 mcp__heygen__generate_video_agent
3. 使用返回的 video_id 调用 mcp__heygen__get_video，轮询状态并获取下载 URL

不使用 MCP 工具（直接调用 API）：

1. 按照 prompt-optimizer.md → visual-styles.md 编写优化后的提示词
2. POST /v1/video_agent/generate — 参见 video-agent.md
3. GET /v2/videos/<id> — 参见 video-status.md

快速参考

任务	MCP 工具	阅读
根据提示词生成视频	mcp__heygen__generate_video_agent	prompt-optimizer.md → visual-styles.md → video-agent.md
检查视频状态 / 获取下载 URL	mcp__heygen__get_video	video-status.md
上传提示词参考文件	—	assets.md

何时使用此技能，何时使用 Avatar Video

此技能适用于基于提示词创建视频——描述你想要的内容，其余工作由 AI 处理。

如果用户需要对特定头像进行精确控制、使用准确脚本、逐场景配置语音/背景或组合多个场景，请改用 avatar-video 技能。

用户说	此技能	Avatar Video 技能
“帮我制作一个关于 X 的视频”	✓
“创建一个产品演示”	✓
“我想让头像 Y 准确说出 Z”		✓
“制作一个背景各不相同的多场景视频”		✓
“用于合成的透明 WebM”		✓

参考文件

核心工作流

• references/prompt-optimizer.md - 编写有效提示词（核心工作流 + 规则）
• references/visual-styles.md - 20 种命名视觉风格的完整规格
• references/prompt-examples.md - 完整的制作提示词示例 + 可直接使用的模板
• references/video-agent.md - Video Agent API 端点详情

基础信息

• references/video-status.md - 轮询模式和下载 URL
• references/webhooks.md - Webhook 端点和事件
• references/assets.md - 上传图片、视频和音频作为参考
• references/dimensions.md - 分辨率和宽高比
• references/quota.md - 积分系统和使用限额

最佳实践

1. 优化提示词 — 结果是平庸还是专业，完全取决于提示词的质量。请始终使用提示词优化器
2. 指定时长 — 使用 config.duration_sec 来确保时长可预测
3. 需要时锁定头像 — 使用 config.avatar_id，确保不同视频中的头像一致
4. 上传参考文件 — 帮助 Agent 了解你的品牌或产品
5. 迭代提示词 — 根据结果进行优化；Video Agent 非常适合快速迭代