heygen-digital-avatar

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HeyGen 数字人口播

Create the avatar layer for a video. Let

ra-video-production-director

own the whole production, captions, QC, and archive; let this skill own HeyGen auth, avatar selection, generation, and the approved avatar layout.

Before writing or approving any HeyGen

motion_prompt

, load and apply

heygen-avatar-motion

. Its motion classes and validation gate are mandatory unless the user explicitly requests a different action. Never submit a paid generation while that validation gate fails.

为视频创建 avatar 图层。由

ra-video-production-director

负责整个制作流程、字幕、QC 和归档；本 skill 负责 HeyGen 身份验证、avatar 选择、生成以及经批准的 avatar 布局。

在编写或批准任何 HeyGen

motion_prompt

之前，加载并应用

heygen-avatar-motion

。除非用户明确要求采取其他操作，否则其 motion 类别和验证关卡均为强制要求。验证关卡未通过时，绝不提交付费生成。

Fixed profile

固定配置

Read

references/pluviobyte-profile.json

before building. Treat it as the machine-readable default. Do not substitute another look from the same avatar group.

Authenticate with HeyGen CLI OAuth and Creator subscription credits. Run HeyGen commands with
```
HEYGEN_API_KEY
```
removed from the child environment so a shell variable cannot silently switch billing lanes.
Use the landscape Digital Twin look the look specified in
```
references/pluviobyte-profile.json
```
For an unspecified digital human, use Avatar III. The exact named preset
```
数字人5
```
always means Avatar V and counts as an explicit premium-engine request; never resolve it to Avatar III. Do not silently substitute a legacy portrait look or a generated suit/scene look from the same avatar group.
Use local IndexTTS2 through
```
tts-skill
```
, voice
```
pluvio-indextts2-calm-v1
```
. Never ask HeyGen to synthesize the voice and never use MiniMax or another fallback for local production.
Treat narration approval as a hard paid-generation gate. Generate the full IndexTTS2 audition first, give the exact audio file to the user, and wait for explicit approval of that version before uploading audio to HeyGen. If the user asks for a digital human without mentioning audio approval, remind them and stop at the audition stage. Any audio edit invalidates prior approval.
Default to the approved
```
headroom_08
```
circular avatar at the lower-left. Only use a full-screen/main-canvas avatar when the user explicitly says
```
全屏数字人
```
or an equivalent unambiguous instruction.
Use the compact neutral circle from the profile: 240px portrait content with one plain white border and no colored accent ring. Keep its bottom alignment stable when changing canvas ratio. Do not restore the older 300px portrait or dark-red outer ring unless the user explicitly requests a larger or emphasized avatar.
Do not trust one fixed crop for every generated master. The standard compositor must sample five frames, measure the face center with macOS Vision, then apply the profile's human-reviewed visual offset. For the approved black-T circle, candidate 06 places the portrait 20px below mathematical face center and keeps the horizontal offset at 0px. Remeasure the finished circle and require the average face center to land within 2px of this offset target. The profile crop is a reviewed fallback, not evidence that a new master is centered.
Keep captions and important content outside the avatar exclusion zone.
Use Avatar IV/V only after the user requests higher quality, invokes the named preset
```
数字人5
```
, or Avatar III fails review. State the expected credit/cost increase before generation. Because
```
数字人5
```
is itself an explicit Avatar V instruction, do not ask the user to reconfirm the engine after giving the cost notice.

构建前读取

references/pluviobyte-profile.json

。将其视为机器可读的默认配置。不得替换为同一 avatar 组中的其他外观。

使用 HeyGen CLI OAuth 和 Creator 订阅额度进行身份验证。运行 HeyGen 命令时，从子环境中移除
```
HEYGEN_API_KEY
```
，避免 shell 变量在无提示的情况下切换计费通道。
使用
```
references/pluviobyte-profile.json
```
中指定的横向 Digital Twin 外观。未指定数字人时，使用 Avatar III。精确命名预设
```
数字人5
```
始终表示 Avatar V，并视为明确的高级 engine 请求；绝不将其解析为 Avatar III。不得静默替换为同一 avatar 组中的旧版竖屏外观或生成的西装/场景造型。
通过
```
tts-skill
```
使用本地 IndexTTS2，语音为
```
pluvio-indextts2-calm-v1
```
。绝不让 HeyGen 合成语音，也绝不在本地制作中使用 MiniMax 或其他 fallback。
将旁白批准视为付费生成的强制关卡。首先生成完整的 IndexTTS2 试音，将准确的音频文件提供给用户，并等待对该版本的明确批准。如果用户要求数字人但未提及音频批准，则提醒用户并停在试音阶段。任何音频编辑都会使先前的批准失效。
默认使用经批准的
```
headroom_08
```
左下角圆形 avatar。只有当用户明确说出
```
全屏数字人
```
或给出同等明确的无歧义指令时，才使用全屏/主画布 avatar。
使用配置中的紧凑中性圆形：240px 竖向头像内容、一圈纯白边框，且不带彩色强调环。更改画布宽高比时，保持其底部对齐稳定。除非用户明确要求更大或更醒目的 avatar，否则不得恢复旧版 300px 头像或深红色外环。
不得对每个生成的母版都信任同一个固定裁剪。标准合成器必须采样五帧，使用 macOS Vision 测量面部中心，然后应用配置中经人工审核的视觉偏移。对于已批准的 black-T 圆形头像，candidate 06 将头像置于数学面部中心下方 20px，并保持水平偏移为 0px。重新测量完成的圆形头像，并要求平均面部中心与该偏移目标的偏差不超过 2px。配置中的裁剪是经审核的 fallback，不能证明新母版已完成居中。
确保字幕和重要内容位于 avatar 排除区域之外。
只有在用户要求更高质量、指定命名预设
```
数字人5
```
，或 Avatar III 未通过审核后，才可使用 Avatar IV/V。生成前说明预计增加的额度/成本。由于
```
数字人5
```
本身就是明确的 Avatar V 指令，因此在给出成本提示后，不要再次要求用户确认 engine。

Workflow

工作流

Run
```
env -u HEYGEN_API_KEY heygen auth status
```
. Require credential type
```
oauth
```
, billing type
```
subscription
```
, and plan
```
creator
```
. Stop before a paid generation if any condition differs.
Generate the complete narration audition with
```
tts-skill
```
; require the canonical WAV and a
```
voice_manifest.json
```
with
```
used_fallback=false
```
and
```
minimax_used=false
```
. Check mixed-language names and technical terms before presenting the audition.
Give the user the exact audition WAV (and optionally a portable MP3) and wait for an explicit confirmation such as “音频确认，可以生成数字人”. Record the approved WAV SHA-256 in
```
media/audio-approval.json
```
. Do not upload audio, build a HeyGen request, or consume credits before this record exists.
Recompute the WAV SHA-256 immediately before upload. If it differs from the approved hash, invalidate the approval, remind the user, and return to step 3. A request to “continue”, “directly produce”, or “make the avatar” is not audio approval unless the user explicitly confirms the audition itself.
Generate production captions from the approved locked audio with
```
ra-audio-to-subtitles
```
. Require
```
caption-qc.json
```
to pass before final composition.
Upload the approved locked WAV with
```
env -u HEYGEN_API_KEY heygen asset create --file <narration.wav>
```
and save the JSON response in the project. Extract its asset ID without copying credentials into files or logs.
Use
```
heygen-avatar-motion
```
to classify each semantic section, save the exact executable motion prompt, and pass its validation gate. Explanatory body sections default to hands fully outside the image; visible hand motion is reserved for meaningful result or conclusion zones.

Resolve the engine from the named preset before building the request. For an unspecified digital human, generate one 16:9, 1080p avatar master with

fit=contain

and

engine.type=avatar_iii

. For

数字人5

, generate the same single master with

engine.type=avatar_v

and pass the premium-engine guard:

bash

python3 scripts/build_request.py \
  --audio-asset-id '<asset-id>' \
  --title '<project title>' \
  --engine avatar_v \
  --allow-premium-engine \
  --output media/heygen-create-request.json
env -u HEYGEN_API_KEY heygen video create \
  -d media/heygen-create-request.json --wait \
  > media/heygen-create-response.json

Download the completed master with
```
heygen video download
```
. Reuse that single master for every requested aspect ratio. Do not spend a second generation merely to change crop, circle placement, background, or canvas ratio.
For the default layout, overlay the master with
```
scripts/compose_circle_avatar.py
```
. Its default
```
--center-mode auto
```
samples the current master, applies the measured crop plus the reviewed visual offset, then verifies the rendered circle against that target. Archive the generated centering report. A Remotion/HyperFrames implementation must reproduce the same measurement, visual offset, and 2px gate rather than copying the fallback coordinates blindly.
For explicit full-screen mode, use the HeyGen master as the main visual and skip the circular compositor. Record
```
layout=fullscreen_explicit
```
in the production note.
Verify media streams, duration, representative frames, subtitle clearance, hair completeness, reduced headroom, voice provenance, and caption QC. Then follow
```
ra-video-production-director
```
for final archive delivery.

运行
```
env -u HEYGEN_API_KEY heygen auth status
```
。要求凭据类型为
```
oauth
```
、计费类型为
```
subscription
```
、套餐为
```
creator
```
。任一条件不符时，必须在付费生成前停止。
使用
```
tts-skill
```
生成完整的旁白试音；要求提供规范 WAV 以及包含
```
used_fallback=false
```
和
```
minimax_used=false
```
的
```
voice_manifest.json
```
。在向用户展示试音前，检查混合语言名称和技术术语。
向用户提供准确的试音 WAV（也可选提供便携式 MP3），并等待明确确认，例如“音频确认，可以生成数字人”。将已批准 WAV 的 SHA-256 记录到
```
media/audio-approval.json
```
。在该记录存在之前，不得上传音频、构建 HeyGen 请求或消耗额度。
上传前立即重新计算 WAV 的 SHA-256。如果与已批准的哈希值不同，则使批准失效，提醒用户并返回步骤 3。用户要求“继续”、“直接制作”或“制作 avatar”并不构成音频批准，除非用户明确确认试音本身。
使用
```
ra-audio-to-subtitles
```
从已批准且锁定的音频生成制作字幕。最终合成前，要求
```
caption-qc.json
```
通过。
使用
```
env -u HEYGEN_API_KEY heygen asset create --file <narration.wav>
```
上传已批准且锁定的 WAV，并将 JSON 响应保存在项目中。提取其 asset ID，但不得将凭据复制到文件或日志中。
使用
```
heygen-avatar-motion
```
对每个语义片段进行分类，保存准确的可执行 motion prompt，并使其通过验证关卡。说明性正文片段默认要求双手完全位于画面之外；只有在有意义的结果或结论片段中才可使用可见的手部动作。

构建请求前，根据命名预设解析 engine。未指定数字人时，使用

fit=contain

和

engine.type=avatar_iii

生成一个 16:9、1080p avatar 母版。对于

数字人5

，使用

engine.type=avatar_v

生成同样的单个母版，并通过高级 engine 防护机制：

bash

python3 scripts/build_request.py \
  --audio-asset-id '<asset-id>' \
  --title '<project title>' \
  --engine avatar_v \
  --allow-premium-engine \
  --output media/heygen-create-request.json
env -u HEYGEN_API_KEY heygen video create \
  -d media/heygen-create-request.json --wait \
  > media/heygen-create-response.json

使用
```
heygen video download
```
下载完成的母版。对于每种请求的宽高比，复用同一个母版。不得仅为更改裁剪、圆形位置、背景或画布宽高比而再次生成并消耗额度。
对于默认布局，使用
```
scripts/compose_circle_avatar.py
```
叠加母版。其默认的
```
--center-mode auto
```
会采样当前母版，应用测量所得的裁剪与经审核的视觉偏移，然后根据目标验证渲染后的圆形头像。归档生成的居中报告。Remotion/HyperFrames 实现必须复现相同的测量方式、视觉偏移和 2px 关卡，而不是盲目复制 fallback 坐标。
对于明确的全屏模式，将 HeyGen 母版用作主视觉，并跳过圆形合成器。在制作说明中记录
```
layout=fullscreen_explicit
```
。
验证媒体流、时长、代表性帧、字幕避让空间、头发完整性、头顶留白缩减情况、语音来源和字幕 QC。随后遵循
```
ra-video-production-director
```
完成最终归档交付。

Standard compositor

标准合成器

Use this when the base edit is already at the requested output size:

bash

python3 scripts/compose_circle_avatar.py \
  --base <base-video.mp4> \
  --avatar <heygen-master.mp4> \
  --output <final.mp4> \
  --layout auto \
  --audio-source avatar \
  --centering-report <centering-report.json>

auto

supports the approved 1920x1080 and 1080x1920 layouts. The avatar audio is authoritative for a narration-only composition. Use

--audio-source base

only when the locked narration is already present in the base edit. Do not mix two copies of the narration.

The adaptive face-measurement pass is mandatory for a newly generated master.

--center-mode profile

uses the reviewed black-T fallback crop only for diagnosis and still must pass the post-render 2px check against the reviewed visual-offset target. Use

--crop-x

and

--crop-y

together only for an explicitly reviewed manual correction. Never regenerate or spend another HeyGen credit merely to correct local framing.

当基础剪辑已达到请求的输出尺寸时，使用：

bash

python3 scripts/compose_circle_avatar.py \
  --base <base-video.mp4> \
  --avatar <heygen-master.mp4> \
  --output <final.mp4> \
  --layout auto \
  --audio-source avatar \
  --centering-report <centering-report.json>

auto

支持已批准的 1920x1080 和 1080x1920 布局。对于仅含旁白的合成，avatar 音频是权威音频源。仅当锁定旁白已存在于基础剪辑中时，才使用

--audio-source base

。不要混合两份旁白。

新生成的母版必须执行自适应面部测量流程。

--center-mode profile

仅将经审核的 black-T fallback 裁剪用于诊断，并且仍须根据经审核的视觉偏移目标通过渲染后的 2px 检查。只有在明确审核过手动修正时，才可同时使用

--crop-x

和

--crop-y

。绝不能仅为修正本地取景而重新生成或再消耗一个 HeyGen 额度。

Credit guard

额度防护

Before generation, state how many HeyGen masters will be created. The default count is one. Layout experiments must use local recomposition and consume zero additional HeyGen credits. Save request/response JSON and the downloaded master under the project so retries can detect and reuse completed work.

生成前，说明将创建多少个 HeyGen 母版。默认数量为一个。布局实验必须使用本地重新合成，并消耗零个额外 HeyGen 额度。将请求/响应 JSON 和下载的母版保存在项目中，以便重试时检测并复用已完成的工作。

Output contract

输出约定

Keep these artifacts in the engineering project:

media/narration.wav

and

media/voice_manifest.json

```
media/audio-approval.json
```
containing the explicitly approved audio SHA-256
```
media/heygen-asset-response.json
```
```
media/heygen-create-request.json
```
```
media/heygen-create-response.json
```
```
media/pluviobyte-avatar-master.mp4
```
production caption artifacts and
```
caption-qc.json
```
final MP4, media probe, contact sheet, and SHA-256 record
centering report with the sampled frames' measurements, reviewed visual-offset target, applied source crop, final average center, per-axis target deviation, tolerance, and
```
status: pass
```

Never store OAuth tokens or API keys in project artifacts.

在工程项目中保留以下产物：

media/narration.wav

和

media/voice_manifest.json

```
media/audio-approval.json
```
，包含明确批准的音频 SHA-256
```
media/heygen-asset-response.json
```
```
media/heygen-create-request.json
```
```
media/heygen-create-response.json
```
```
media/pluviobyte-avatar-master.mp4
```
制作字幕产物和
```
caption-qc.json
```
最终 MP4、媒体探测结果、联系表和 SHA-256 记录
居中报告，包含采样帧的测量值、经审核的视觉偏移目标、应用的源裁剪、最终平均中心、各轴目标偏差、容差以及
```
status: pass
```

绝不在项目产物中存储 OAuth token 或 API key。