create-video

创建视频

从文本提示词生成完整视频。描述你的需求，AI 会自动处理脚本撰写、虚拟形象选择、视觉效果、配音、节奏和字幕。

身份验证

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

curl -X POST "https://api.heygen.com/v3/video-agents" \
  -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 /v3/video-agents
检查视频状态／获取 URL	mcp__heygen__get_video	GET /v3/videos/{video_id}
列出账户视频	mcp__heygen__list_videos	GET /v3/videos
删除视频	mcp__heygen__delete_video	DELETE /v3/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 /v3/video-agents — 参见 video-agent.md
3. GET /v3/videos/<id> — 参见 video-status.md

参考文件

按需阅读这些文件——其中包含端点详情、请求／响应架构和代码示例（curl、TypeScript、Python）。

核心工作流：

• references/prompt-optimizer.md — 编写有效的提示词（场景、时间安排、视觉风格）
• references/visual-styles.md — 20 种命名视觉风格的完整规范
• references/prompt-examples.md — 适用于生产环境的提示词示例和模板
• references/video-agent.md — POST /v3/video-agents 请求字段、响应格式和文件输入

基础功能：

• references/video-status.md — GET /v3/videos/{id} 轮询和下载
• references/webhooks.md — Webhook 端点和事件
• references/assets.md — 上传图片、视频和音频作为参考
• references/dimensions.md — 分辨率和宽高比
• references/quota.md — 积分系统和使用限制

最佳实践

1. 优化提示词 — 质量完全取决于提示词结构。始终使用提示词优化器
2. 需要时固定虚拟形象 — 传入 avatar_id，以确保不同视频中的形象一致
3. 指定语音 — 传入 voice_id，以选择特定的旁白音色
4. 上传参考文件 — 帮助 Agent 了解你的品牌／产品
5. 迭代优化提示词 — 根据结果不断完善；Video Agent 非常适合快速迭代