Back to Details

avatar-video

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Avatar Video

Avatar视频

Create AI avatar videos with full control over avatars, voices, scripts, scenes, and backgrounds. Build single or multi-scene videos with exact configuration using HeyGen's 
/v2/video/generate
API.
创建AI Avatar视频，可全面控制Avatar、语音、脚本、场景及背景。借助HeyGen的
/v2/video/generate
API，按照精确配置制作单场景或多场景视频。

Authentication

身份验证

All requests require the 
X-Api-Key
header. Set the 
HEYGEN_API_KEY
environment variable.
bash
curl -X GET "https://api.heygen.com/v2/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
所有请求均需携带
X-Api-Key
请求头。请设置
HEYGEN_API_KEY
环境变量。
bash
curl -X GET "https://api.heygen.com/v2/avatars" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Tool Selection

工具选择

If HeyGen MCP tools are available (
mcp__heygen__*
), prefer them over direct HTTP API calls — they handle authentication and request formatting automatically.
TaskMCP ToolFallback (Direct API)
Check video status / get URL
mcp__heygen__get_video
GET /v2/videos/{video_id}
List account videos
mcp__heygen__list_videos
GET /v2/videos
Delete a video
mcp__heygen__delete_video
DELETE /v2/videos/{video_id}
Video generation (
POST /v2/video/generate
) and avatar/voice listing are done via direct API calls — see reference files below.
若HeyGen MCP工具可用（
mcp__heygen__*
），优先使用此类工具而非直接调用HTTP API——它们会自动处理身份验证和请求格式。
任务MCP工具备选方案（直接调用API）
查询视频状态/获取视频链接
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}
视频生成（
POST /v2/video/generate
）以及Avatar/语音列表查询需通过直接调用API完成——详见下方参考文档。

Default Workflow

默认工作流程

  1. List avatars — 
    GET /v2/avatars
    → pick an avatar, preview it, note 
    avatar_id
    and 
    default_voice_id
    . See avatars.md
  2. List voices (if needed) — 
    GET /v2/voices
    → pick a voice matching the avatar's gender/language. See voices.md
  3. Write the script — Structure scenes with one concept each. See scripts.md
  4. Generate the video — 
    POST /v2/video/generate
    with avatar, voice, script, and background per scene. See video-generation.md
  5. Poll for completion — 
    GET /v2/videos/{video_id}
    until status is 
    completed
    . See video-status.md
  1. 列出Avatar — 调用
    GET /v2/avatars
    → 选择一个Avatar，预览它，记录
    avatar_id
    和
    default_voice_id
    。详见avatars.md
  2. 列出语音（如需） — 调用
    GET /v2/voices
    → 选择与Avatar性别/语言匹配的语音。详见voices.md
  3. 编写脚本 — 为每个场景构建单一主题的脚本。详见scripts.md
  4. 生成视频 — 调用
    POST /v2/video/generate
    ，传入每个场景对应的Avatar、语音、脚本及背景。详见video-generation.md
  5. 轮询完成状态 — 调用
    GET /v2/videos/{video_id}
    ，直到状态变为
    completed
    。详见video-status.md

Quick Reference

快速参考

TaskRead
List and preview avatarsavatars.md
List and select voicesvoices.md
Write and structure scriptsscripts.md
Generate video (single or multi-scene)video-generation.md
Add custom backgroundsbackgrounds.md
Add captions / subtitlescaptions.md
Add text overlaystext-overlays.md
Create transparent WebM videovideo-generation.md (WebM section)
Use templatestemplates.md
Create avatar from photophoto-avatars.md
Check video status / downloadvideo-status.md
Upload assets (images, audio)assets.md
Use with Remotionremotion-integration.md
Set up webhookswebhooks.md
任务参考文档
列出并预览Avataravatars.md
列出并选择语音voices.md
编写并结构化脚本scripts.md
生成视频（单场景或多场景）video-generation.md
添加自定义背景backgrounds.md
添加字幕captions.md
添加文字叠加层text-overlays.md
创建透明WebM视频video-generation.md（WebM章节）
使用模板templates.md
从照片创建Avatarphoto-avatars.md
查询视频状态/下载视频video-status.md
上传资源（图片、音频）assets.md
与Remotion集成remotion-integration.md
设置Webhookwebhooks.md

When to Use This Skill vs Create Video

本技能与Create Video技能的适用场景对比

This skill is for precise control — you choose the avatar, write the exact script, configure each scene.
If the user just wants to describe a video idea and let AI handle the rest (script, avatar, visuals), use the create-video skill instead.
User SaysCreate Video SkillThis Skill
"Make me a video about X"✓
"Create a product demo"✓
"I want avatar Y to say exactly Z"✓
"Multi-scene video with different backgrounds"✓
"Transparent WebM for compositing"✓
"Use this specific voice for my script"✓
"Batch generate videos with exact specs"✓
本技能适用于精准控制场景——由你选择Avatar、编写精准脚本、配置每个场景。
若用户仅希望描述视频创意，并交由AI处理其余部分（脚本、Avatar、视觉效果），则应使用create-video技能。
用户需求Create Video技能本技能
"帮我制作一个关于X的视频"✓
"创建一个产品演示视频"✓
"我想要Avatar Y精准朗读内容Z"✓
"制作多场景且每个场景背景不同的视频"✓
"创建用于合成的透明WebM视频"✓
"为我的脚本使用指定的语音"✓
"按照精确规格批量生成视频"✓

Reference Files

参考文档

Core Video Creation

核心视频创建

  • references/avatars.md - Listing avatars, styles, avatar_id selection
  • references/voices.md - Listing voices, locales, speed/pitch
  • references/scripts.md - Writing scripts, pauses, pacing
  • references/video-generation.md - POST /v2/video/generate and multi-scene videos
  • references/avatars.md - 列出Avatar、风格，选择
    avatar_id
  • references/voices.md - 列出语音、区域设置、语速/音调
  • references/scripts.md - 编写脚本、停顿、节奏
  • references/video-generation.md - 调用
    POST /v2/video/generate
    及多场景视频制作

Video Customization

视频自定义

  • references/backgrounds.md - Solid colors, images, video backgrounds
  • references/text-overlays.md - Adding text with fonts and positioning
  • references/captions.md - Auto-generated captions and subtitles
  • references/backgrounds.md - 纯色、图片、视频背景
  • references/text-overlays.md - 添加带字体和位置设置的文字
  • references/captions.md - 自动生成字幕

Advanced Features

高级功能

  • references/templates.md - Template listing and variable replacement
  • references/photo-avatars.md - Creating avatars from photos
  • references/webhooks.md - Webhook endpoints and events
  • references/templates.md - 模板列表及变量替换
  • references/photo-avatars.md - 从照片创建Avatar
  • references/webhooks.md - Webhook端点及事件

Integration

集成

  • references/remotion-integration.md - Using HeyGen in Remotion compositions
  • references/remotion-integration.md - 在Remotion合成中使用HeyGen

Foundation

基础功能

  • references/video-status.md - Polling patterns and download URLs
  • references/assets.md - Uploading images, videos, audio
  • references/dimensions.md - Resolution and aspect ratios
  • references/quota.md - Credit system and usage limits
  • references/video-status.md - 轮询模式及下载链接
  • references/assets.md - 上传图片、视频、音频
  • references/dimensions.md - 分辨率及宽高比
  • references/quota.md - 积分系统及使用限制

Best Practices

最佳实践

  1. Preview avatars before generating — Download 
    preview_image_url
    so the user can see the avatar before committing
  2. Use avatar's default voice — Most avatars have a 
    default_voice_id
    pre-matched for natural results
  3. Fallback: match gender manually — If no default voice, ensure avatar and voice genders match
  4. Use test mode for development — Set 
    test: true
    to avoid consuming credits (output will be watermarked)
  5. Set generous timeouts — Video generation often takes 5-15 minutes, sometimes longer
  6. Validate inputs — Check avatar and voice IDs exist before generating
  1. 生成前预览Avatar — 下载
    preview_image_url
    ，让用户在确认生成前查看Avatar效果
  2. 使用Avatar的默认语音 — 大多数Avatar都有预先匹配的
    default_voice_id
    ，可获得更自然的效果
  3. 备选方案：手动匹配性别 — 若没有默认语音，确保Avatar与语音的性别匹配
  4. 开发时使用测试模式 — 设置
    test: true
    以避免消耗积分（输出视频将带有水印）
  5. 设置充足的超时时间 — 视频生成通常需要5-15分钟，有时会更长
  6. 验证输入信息 — 生成前检查Avatar和语音ID是否存在