创建视频
从文本提示生成完整视频。描述您想要的内容,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": "制作一个60秒的产品演示视频。"}'
工具选择
如果 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 工具:
- 使用 prompt-optimizer.md → visual-styles.md 编写优化后的提示
- 使用提示和配置(
duration_sec,orientation,avatar_id)调用mcp__heygen__generate_video_agent - 使用返回的
video_id调用mcp__heygen__get_video轮询状态并获取下载 URL
不使用 MCP 工具(直接 API):
- 使用 prompt-optimizer.md → visual-styles.md 编写优化后的提示
POST /v1/video_agent/generate— 参见 video-agent.mdGET /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 |
何时使用此技能 vs 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 - 信用点数系统与使用限制
最佳实践
- 优化您的提示——平庸与专业结果之间的差距完全取决于提示质量。始终使用提示优化器。
- 指定时长——使用
config.duration_sec来获得可预测的长度。 - 必要时锁定虚拟形象——使用
config.avatar_id以保证不同视频间的一致性。 - 上传参考文件——帮助代理理解您的品牌/产品。
- 迭代提示——根据结果进行优化;Video Agent 非常适合快速迭代。