创建视频
根据文本提示生成完整视频。描述你的需求,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 编写优化后的提示
- 调用
mcp__heygen__generate_video_agent,传入提示和配置(duration_sec、orientation、avatar_id) - 调用
mcp__heygen__get_video,传入返回的 video_id 以轮询状态并获取下载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 虚拟形象视频
此技能用于基于提示的视频创作——描述你的需求,AI处理其余部分。
如果用户需要对特定虚拟形象、精确脚本、每个场景的语音/背景配置或多场景合成进行精确控制,请改用 avatar-video 技能。
| 用户说 | 此技能 | 虚拟形象视频技能 |
|---|---|---|
| “给我做一个关于X的视频” | ✓ | |
| “创建产品演示” | ✓ | |
| “我想要虚拟形象Y精确地说Z” | ✓ | |
| “包含不同背景的多场景视频” | ✓ | |
| “用于合成的透明WebM” | ✓ |
参考文件
核心工作流
- references/prompt-optimizer.md - 编写有效的提示(核心工作流 + 规则)
- references/visual-styles.md - 20种命名视觉风格及完整规格
- references/prompt-examples.md - 完整的生成式提示示例 + 即用模板
- references/video-agent.md - 视频智能体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实现跨视频的一致性 - 上传参考文件——帮助智能体理解你的品牌/产品
- 迭代提示——根据结果进行优化;视频智能体非常适合快速迭代