Heygen Digital Avatar

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.

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.

Workflow

1. 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.

2. 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.

3. 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.

4. 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.

5. Generate production captions from the approved locked audio with ra-audio-to-subtitles. Require caption-qc.json to pass before final composition.

6. 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.

7. 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.

8. 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:

   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
   

9. 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.

10. 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.

11. 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.

12. 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.

Standard compositor

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

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.

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.

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.