heygen-avatar-video

HeyGen 虚拟形象视频制作

当制作流程使用 HeyGen，且交付内容涉及 AI 主持人、数字分身、照片虚拟形象、工作室虚拟形象、通过提示词创作的虚拟形象片段或实时流式虚拟形象时，使用此技能。将 HeyGen 视为兼具创意视频工具和肖像处理系统的产品：生成前，先确认同意、身份权利、脚本意图、声音权利和输出保管责任。

以下信息已于 2026-07-10 根据 HeyGen 官方文档和政策页面核实。付费运行前，请重新检查链接文档中可能变动的信息，例如价格、引擎支持、端点格式、限制、状态值、审核政策和套餐权益。

选择合适的 HeyGen 路径

优先选择符合需求且可控性最高的 API。

• 当用户希望根据自然语言需求生成完整的虚拟形象视频，并接受 HeyGen 选择或创作脚本、虚拟形象、声音和视觉风格时，使用 Video Agent（POST /v3/video-agents）。这是最快的探索路径，支持一次性生成或交互式聊天迭代，但对场景的控制较不确定。
• 当脚本、虚拟形象外观、声音、宽高比、背景、字幕、水印、输出格式或动作提示词必须明确且可重复时，使用 Direct Video（POST /v3/videos，type: "avatar"）。这是制作流程、个性化营销活动、经过合规审核的脚本和品牌管控的代言人视频的默认选择。
• 仅当输出是通过提示词创作的简短电影感镜头，包含 1-3 种虚拟形象外观且没有口播脚本时，使用 Cinematic Avatar（POST /v3/videos，type: "cinematic_avatar"）。不要将其用于常规的对镜头口播。
• 当用户需要虚拟形象实时说话的 HLS 直播流时，使用 Avatar Realtime（POST /v3/avatar-realtime）。它适用于自助服务终端、实时 Agent、助手和由应用负责 STT/LLM 编排的广播场景。它不是渲染 MP4 的工作流。
• 当必须保留视频画面来源时，使用 Video Translation 或 Lipsync API 对现有素材进行后期本地化或替换音频，而不是重新生成整个视频。

官方路径依据：HeyGen 的“Choosing the Right Video API”文档将 Video Agent 描述为由提示词驱动、控制较少；将 Direct Video 描述为结构化、控制较强；将 Cinematic Avatar 描述为由提示词和虚拟形象外观构成且没有口播声音。官方 Avatar Realtime 文档说明，实时 HLS 路径与渲染视频相互独立。

预检清单

生成前：

1. 确认身份验证路径和计费余额。
   • 直接 API 和技能使用 X-Api-Key / x-api-key，费用从 API 钱包扣除。
   • 基于 OAuth 的 MCP/Agent 用法可以改从网页套餐余额扣除。
2. 选择上述 API 路由，并记录选择原因。
3. 使用 GET /v3/avatars/looks 列出可用的头像外观；将外观 ID 作为 avatar_id 传入，而不是头像组 ID。
4. 使用 GET /v3/voices 列出可用语音；必要时按语言、性别、类型和引擎筛选。如果使用 TTS 端点，HeyGen 文档指出应选择 engine=starfish 语音。
5. 核实任何数字分身的同意状态。除非真人明确许可且符合 HeyGen 的同意要求，否则不要生成其肖像。
6. 根据输出时长和所选功能估算费用。定价可能变动；在批量处理或付费生产前，务必立即核实当前 API 或企业定价。
7. 确认资源限制和文件可访问性：
   • 传给 API 的 URL 必须可公开访问，并且直接指向文件。
   • 官方文档列出了支持的上传格式和大小限制；对于较大的文件，请使用直接上传流程。
8. 制定生命周期策略：回调 URL、轮询频率、失败处理、本地工件存储，以及预签名 URL 过期前的下载安排。
9. 在渲染前定义 QA 验收标准：发音、口型同步、身份/肖像、手势是否得当、品牌/背景、字幕、宽高比，以及安全/审核状态。

头像、外观和同意处理

HeyGen 将头像组与头像外观区分开来。头像组代表角色身份；头像外观则是可用于渲染的服装/姿势/风格。创建视频时，avatar_id 应为外观 ID。

数字分身描绘的是可识别的真人，需要明确处理同意事项。HeyGen 的同意文档指出，数字分身需要提供证据，证明被描绘者同意克隆其形象；而照片头像和提示词头像不需要遵循相同的数字分身同意流程。可用的同意级别，核实于 2026-07-10：

• Level 1：托管式网络摄像头同意页面；v3 中可用。
• Level 2：通过 API 上传预先录制的同意视频；仅限企业客户/白名单用户。
• Level 3：为有特殊企业安排的账户跳过同意流程；仅限白名单用户。

生产规则：

• 如果用户要求冒充、克隆或使用未经明确授权和同意的私人个人、员工、名人、公众人物或客户，应立即停止。
• 如果头像主体可被识别且不是请求者本人，请求其提供权利证明。
• 除非事实如此且已获授权，否则不要将素材库/头像库中的外观描述为真实员工或真实客户。
• 保留审计记录，包含头像组/外观 ID、所有权（已知时注明 private 或素材库/头像库）、同意状态，或可用时的同意 URL/结果，以及审批来源。
• 如果已创建数字分身但尚未获得同意，请通过 POST /v3/avatars/{group_id}/consent 发起流程，并等待完成/批准后再生成。

Direct Video 的引擎选择

对于 POST /v3/videos 虚拟形象渲染，HeyGen v3 支持 Avatar III、Avatar IV 和 Avatar V 引擎。验证日期：2026-07-10：

• 若省略 engine 字段，默认使用 Avatar IV（avatar_iv）。对于常规 Direct Video，这是最稳妥的默认选择，因为它的支持范围较广。
• Avatar V（avatar_v）保真度更高，且在 HeyGen 的文档和研究中以交叉参考为依据，但官方文档建议在请求前，通过 GET /v3/avatars/looks/{look_id} 检查虚拟形象外观的 supported_api_engines。Avatar V 的支持范围较窄，定价和模型文档注明它仅适用于 Digital Twin。
• Avatar III（avatar_iii）在当前 v3 文档中是一条专用的照片转视频处理流程。不要将它与旧版 legacy v1/v2 Avatar III 端点混淆。
• motion_prompt 是否受支持，取决于虚拟形象来源和引擎：官方 v3 文档列出，它适用于任一受支持引擎下的照片虚拟形象，也适用于 engine.type 为 avatar_v 时的视频虚拟形象；默认 Avatar IV 引擎下的视频虚拟形象不接受此参数。expressiveness 仅适用于照片虚拟形象，且仅支持 Avatar IV；与 Avatar V 搭配时会被拒绝。

经验法则：对于经过合规审核的企业或培训讲解者，使用 Avatar IV，除非明确支持 Avatar V，且用户足够重视最高程度的相似度／动作保真度，或视频虚拟形象的手势提示功能，愿意为此付费。对于照片虚拟形象实验，请检查 Avatar III 或 IV 哪个更符合可用外观和成本限制。

脚本和表演指引

脚本应面向真人讲解者，而不是将配音直接贴到一张脸上。

• 句子要简短、便于换气。每句话表达一个意思。
• 避免使用复杂的缩写和数字，除非目标受众需要；必要时在脚本中标注读音。
• 通过 HeyGen 支持的字段添加舞台指示；除非某个字段会专门将方括号中的表演提示解释为指示，否则不要把这些提示塞进口播文本。
• 仅在所选虚拟形象／引擎组合支持时，使用 motion_prompt 指定可见行为：姿势、手势克制程度、亲和力、指向／手势幅度、眼神交流方式和活力。保持自然，避免编排感。
• 如果所选声音支持相关设置，请使用 voice_settings 设置语速、音高、音量、地区语言和引擎选项。
• 本地化时，不要逐字翻译。应根据目标语言调整脚本时长，然后选择声音／地区语言，并检查口型同步和字幕适配情况。

虚拟形象视频的脚本结构：

• 开场钩子：前 3-5 秒，直面镜头讲述。
• 背景：用一句话点明观众的问题。
• 价值：分为 2-4 个简短要点；列表应采用平行语法。
• 证明／演示：提供一个具体示例或视觉参考。
• 行动号召：只提出一个行动，不要堆砌多个要求。

避免：

• 使用让嘴唇连续运动、没有自然停顿的长从句。
• 在口播脚本中加入时间戳或剪辑备注。
• 提出虚拟形象所代表的主体无权提出的主张。
• 未获许可的品牌比较、对医疗／法律／财务事项作确定性承诺，或带有欺骗性的代言措辞。

Direct Video 请求模式

受控渲染视频使用此模式：

{
  "type": "avatar",
  "avatar_id": "LOOK_ID",
  "voice_id": "VOICE_ID",
  "script": "Hi, I'm Maya. In the next thirty seconds, I'll show you how Acme reduces invoice review from days to minutes.",
  "title": "Acme invoice review intro",
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "background": {
    "asset_id": "BACKGROUND_ASSET_ID"
  },
  "caption": {
    "file_format": "srt",
    "style": "default"
  },
  "engine": {
    "type": "avatar_iv"
  },
  "callback_url": "https://example.com/webhooks/heygen",
  "callback_id": "project-scene-001"
}

制作备注：

• 如果用户提供了获批的旁白，并希望与该音频进行口型同步，请使用 audio_url 或 audio_asset_id，而不是 script + voice_id。
• 仅当所选虚拟形象外观和引擎支持时才添加 motion_prompt；默认 Avatar IV 下的视频虚拟形象或数字分身渲染不要包含此参数。
• 仅当下游合成器需要将虚拟形象单独分离出来时，才使用 remove_background 或透明背景／背景处理工作流；请确认所选端点／套餐是否支持所需的输出格式。
• 确保 callback_id 有意义且唯一，以便追踪保管流程；并将其同步到本地清单中。
• 如果没有可用的回调，请轮询 GET /v3/videos/{video_id}，直到状态进入终止状态。

Video Agent 提示词模式

当速度和创意自动化比精确控制更重要时，使用 Video Agent。提示词仍应明确指定业务限制；不要让品牌、受众、时长或合规敏感声明处于隐含状态。

提示词示例：

Create a 45-second avatar-led onboarding video for a B2B SaaS feature launch.
Audience: finance operations managers.
Goal: explain that Acme Review flags duplicate invoices before payment.
Tone: calm, credible, lightly upbeat; no hype.
Structure: 5-second hook, one pain point, three product benefits, one concrete example, CTA to book a demo.
Visual style: clean enterprise software, soft blue/white palette, no exaggerated gestures.
Must say: "duplicate invoice checks run before the payment batch is approved."
Avoid: guarantees of fraud prevention, competitor claims, fake customer quotes, legal advice.
Output: 16:9, captions on.

如果用户需要精确措辞，不要依赖 Video Agent 撰写最终脚本。可以用它探索创意，然后使用经批准的脚本和明确指定的素材，重新构建为 Direct Video。

Avatar Realtime 制作模式

Avatar Realtime 适用于实时口播虚拟形象，而非交付 MP4。官方文档介绍了三种语音驱动方式：tts、audio 和 text_stream；会话通过 HLS 播放。

对于 text_stream，请规划上游系统：

• 如果存在语音输入，则需要 STT。
• 能生成简短响应片段的大模型或规则引擎。
• 在追加文本前进行脏话／安全过滤。
• 处理背压，避免虚拟形象收到过长且已过时的响应。
• 处理空闲超时；官方文档列出的 text_stream 默认空闲超时时长为 30 秒。
• 处理会话时长上限和并发；官方文档列出的会话时长上限为一小时，每个空间默认允许三个并发会话，且限制可调整。

实时 QA 包括启动延迟、中断行为、流稳定性、HLS 播放器兼容性、end_reason／错误消息，以及虚拟形象的口播响应是否与用户的实际问题保持一致。

背景、场景、字幕与品牌

HeyGen Direct Video 可对单个虚拟形象渲染进行结构化控制；除非所选路线支持场景／模板，否则不要假定它是完整的编辑器。对于多场景品牌视频：

• 如果 Video Agent 能自动组合场景并应用样式，则使用它。
• 如果每个场景都需要不同的脚本片段、背景或构图，则使用 Direct Video 多次渲染，然后在下游进行合成。
• 使用 Assets API 上传自定义背景或视觉素材，并引用返回的 asset_id。
• 如果目标平台默认静音播放，则添加字幕。务必检查 SRT 时间和换行。
• 仅在品牌／合规要求时添加水印；避免遮挡虚拟形象的脸部或下三分之一字幕。

产物保管：

• 保存请求载荷，但移除机密信息。
• 保存响应 ID：video_id、callback_id、虚拟形象外观 ID、语音 ID、素材 ID、引擎类型和标题。
• 将已完成的 video_url 产物立即下载到项目存储中；预签名链接不能作为长期保管方式。
• 如果有缩略图、字幕、生成的音频和最终 MP4，请分别存储。
• 在制作日志中逐字记录审核／拒绝／失败消息。

轮询、回调与失败

渲染视频的生成过程是异步的。官方文档列出了视频状态，包括 pending、processing、completed 和 failed；已完成的响应包含 video_url，失败的响应则包含失败详情。大规模运行时使用回调，简单运行时使用轮询。

故障排查：

• 401 Unauthorized：API 密钥缺失、请求头错误、密钥未激活，或计费/身份验证路径错误。
• 429 Too Many Requests：速率或并发限制。遵守 Retry-After；不要紧密循环重试。
• 下载/资源失败：公开 URL 无法访问、文件扩展名与内容不符、格式不受支持、素材过大、文件损坏，或 URL 需要身份验证。
• 验证错误：头像外观与引擎不匹配、所选头像/引擎不支持 motion_prompt、Avatar V 或非照片头像不支持 expressiveness、缺少脚本/音频/语音字段、宽高比/分辨率无效，或提示词/脚本过长。
• 审核/待处理/拒绝：内容或肖像相似性审查。不要反复提交试图规避审核的变体；应修改内容以符合政策，或升级处理并请求人工审核。
• 临近完成时渲染失败：获取 failure_code/failure_message，保留请求，并使用最简脚本和相同头像/语音进行测试，以确定问题出在内容、素材、引擎还是账户限制。

重试策略：

• 可安全重试：退避后遇到的临时 429/5xx、回调投递失败，或未返回任务 ID 时发生的网络超时。
• 谨慎重试：确认并非审核或验证问题后，使用相同负载重试渲染失败的任务。
• 不要对未更改的内容重试：权利/同意问题、审核拒绝、引擎不受支持，或素材 URL 无法访问。

安全、政策与如实披露

HeyGen 当前的官方页面要求用户遵守其《条款》和《可接受使用/审核政策》，并强调创建自定义头像/数字分身时必须取得同意。请建立自己的生产审核关卡：

• 必须获得明确许可，才能使用可识别的肖像和声音。
• 避免欺骗性冒充、虚假代言、假新闻/访谈，或在必须披露或基于具体情境应当披露时隐瞒合成身份。
• 确保内容符合 HeyGen 的审核边界和适用法律。
• 如果观众有理由相信出镜者是真实员工/客户/官员，且这一点会影响其决策，请添加“AI 生成的演示者”等披露信息。
• 不得将克隆的声音或头像用于敏感游说、欺诈、骚扰、色情内容、违反儿童安全规定的内容、政治欺骗，或冒充真实专业人士提供医疗/法律/财务建议。
• 将同意证明以及下架/删除请求作为生产关键记录予以保存。

QA 审查标准

交付前审查下载的视频：

• 身份与权利：头像已获授权且使用正确；没有意外造成身份误导。
• 脚本准确性：准确呈现已批准的主张；Video Agent 未生成幻觉内容。
• 语音：语言/地区设置正确，发音和节奏合适，情感契合，没有词语被截断。
• 唇形同步：音节时序准确，嘴部闭合自然，爆破音表现正常，长句中没有不同步。
• 动作：手势符合脚本；没有诡异的手部/面部瑕疵；眼神交流自然。
• 视觉效果：宽高比、构图、安全边距、背景、品牌颜色、水印和字幕均符合要求。
• 无障碍性：字幕易读且未被遮挡；音量稳定；没有仅通过视觉呈现的关键信息。
• 平台适配：时长、格式和首帧/吸引点符合发布平台要求。
• 归档：已保存最终 MP4、字幕、缩略图、请求/响应清单和源素材 ID。
• 合规性：已记录同意、披露、审核状态和审批备注。

完整示例：受控的产品发布会发言人

意图：制作一段确定性的 30 秒产品发布视频，采用经批准的公司演讲者形象。

方法：

1. 确认演讲者同意使用其私人数字分身形象，并确认相关权利归属。
2. 列出头像形象和声音；选择经批准的形象和品牌声音。
3. 检查 GET /v3/avatars/looks/{look_id} 支持的引擎；如果未列出 Avatar V，则使用 Avatar IV。
4. 如果经批准的办公室背景尚未公开且稳定，则将其上传至 Assets API。
5. 通过 Direct Video 生成视频，并设置回调和字幕。
6. 下载最终 MP4 并进行质量检查。

示例负载：

{
  "type": "avatar",
  "avatar_id": "maya_launch_look_01",
  "voice_id": "en_us_brand_voice_02",
  "script": "Today we're launching Acme Review. It checks every invoice before the payment batch is approved, flags likely duplicates, and gives your team a clear review queue. If you already use Acme Pay, you can turn it on from settings today.",
  "title": "Acme Review launch - approved spokesperson",
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "background": { "asset_id": "asset_office_soft_blue" },
  "caption": { "file_format": "srt", "style": "default" },
  "engine": { "type": "avatar_iv" },
  "callback_url": "https://video.example.com/hooks/heygen",
  "callback_id": "acme-review-launch-v1"
}

为何有效：经批准的脚本避免了无法核实的保证；对于受控的发言人视频渲染，Avatar IV 是适用范围广的默认选择；回调 ID 便于追踪交付链；Direct Video 则能保留确切措辞。如果经批准的数字分身形象支持 Avatar V，且手势提示很重要，则在确认支持后切换引擎，再添加克制的 motion_prompt。

可能的失败模式：不支持私人形象、数字分身同意仍待确认、产品名称发音不准确、字幕与下方字幕条重叠，或因声明暗示对欺诈检测作出保证而触发审核。

完整示例：本地化培训模块

意图：将一段英语 HR 培训演讲视频改编为西班牙语和法语版本，同时保留经批准的视觉形象。

方法：

1. 将每种语言都视为新的脚本改编，而不是逐字翻译。
2. 只有在相关权利涵盖本地化用途时，才保留相同的头像形象。
3. 按目标地区选择声音，并检查姓名、政策术语和缩略词的发音。
4. 每种语言分别使用符合当地语言习惯的脚本和声音设置，通过 Direct Video 生成视频。
5. 检查母语语速、口型同步、字幕和政策措辞。

西班牙语脚本片段示例：

Hola. En este modulo repasaremos como reportar un conflicto de intereses antes de aprobar una compra. Si tienes dudas, pausa el video y consulta la politica interna en el portal de cumplimiento.

负载差异示例：

{
  "voice_id": "es_es_training_voice_01",
  "voice_settings": {
    "speed": 0.95,
    "pitch": 0,
    "volume": 1,
    "locale": "es-ES"
  },
  "caption": {
    "file_format": "srt",
    "style": "default"
  }
}

为何有效：略慢的语速为字幕和口型同步留出了更多空间，而为每种语言单独编写脚本则能保留各市场的合规措辞。

可能的失败模式：译文句子过长、正式与非正式称谓不一致、克隆声音未获准在所有地区使用，以及字幕文字溢出。

完整示例：实时礼宾头像

意图：在自助服务终端中的实时支持助手上呈现头像。

方法：

1. 使用 Avatar Realtime，而不是渲染后的 Direct Video。
2. 选择库存或已获授权的头像形象和合适的声音。
3. 打开 text_stream 会话。
4. 轮询，直到 HLS URL 可用。
5. 在应用自身完成 STT、LLM、检索和安全检查后，分段传输简短回答。
6. 在闲置或自助服务终端重置时，取消或关闭会话。

初始请求示例：

{
  "type": "text_stream",
  "avatar_id": "concierge_stock_look_07",
  "voice_id": "en_us_warm_support_03",
  "text": "Hi, I'm here to help. What can I find for you today?"
}

追加文本示例：

{
  "text": "The returns desk is on level two, near the west elevators."
}

为何有效：Avatar Realtime 只负责说话头像和声音流；检索准确性、安全过滤和对话状态仍由应用负责。

可能的失败模式：闲置超时、并发会话过多、自助服务终端浏览器上的 HLS 播放问题、用户更换话题后仍排队等待播报的大模型长回答，或头像看起来像是在作出系统无法兑现的承诺。

官方和权威来源

• HeyGen API 快速入门：https://developers.heygen.com/docs/quick-start
• HeyGen API 密钥指南：https://developers.heygen.com/docs/api-key
• HeyGen 如何选择合适的视频 API：https://developers.heygen.com/docs/choosing-the-right-video-api
• HeyGen 创建视频参考：https://developers.heygen.com/reference/create-video
• HeyGen 获取视频参考：https://developers.heygen.com/reference/get-video
• HeyGen 数字分身指南：https://developers.heygen.com/generate-avatar-video
• HeyGen Avatar 实时指南：https://developers.heygen.com/avatar-realtime
• HeyGen Avatar 同意指南：https://developers.heygen.com/docs/avatar-consent
• HeyGen 创建 Avatar 指南：https://developers.heygen.com/docs/create-avatar
• HeyGen Avatar 外观参考：https://developers.heygen.com/reference/list-avatar-looks
• HeyGen 语音参考：https://developers.heygen.com/reference/list-voices
• HeyGen 上传素材指南：https://developers.heygen.com/docs/upload-assets
• HeyGen 自助定价和限制：https://developers.heygen.com/docs/pricing
• HeyGen 企业定价和限制：https://developers.heygen.com/docs/enterprise-pricing
• HeyGen 更新日志：https://developers.heygen.com/changelog
• HeyGen 内容审核政策：https://www.heygen.com/moderation-policy
• HeyGen 条款：https://www.heygen.com/terms
• HeyGen 隐私政策：https://www.heygen.com/privacy
• HeyGen Avatar V 研究页面：https://www.heygen.com/research/avatar-v-model