创建视频
从文本提示生成完整视频。描述你需要的,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. 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 - 视频智能体 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确保跨视频的一致性 - 上传参考文件 —— 帮助智能体了解你的品牌/产品
- 迭代提示 —— 根据结果进行优化;视频智能体非常适合快速迭代