🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Avatar Video
πŸ¦€ ClawHub

Avatar Video

by @michaelwang11394

Create AI avatar videos with precise control over avatars, voices, scripts, and backgrounds using HeyGen's v3 API (POST /v3/videos). Two modes: type="avatar"...

Versionv2.23.0
Downloads752
Installs1
Stars⭐ 1
#crypto#clawhub
TERMINAL
clawhub install avatar-video

πŸ“– About This Skill

name: avatar-video description: | Create AI avatar videos with precise control over avatars, voices, scripts, and backgrounds using HeyGen's v3 API (POST /v3/videos). Two modes: type="avatar" with avatar_id, or type="image" with an image AssetInput (Avatar IV). Use when: (1) Choosing a specific avatar and voice for a video, (2) Writing exact scripts for an avatar to speak, (3) Animating a photo into a speaking video (type="image"), (4) Transparent background videos with remove_background, (5) Integrating HeyGen avatars with Remotion, (6) Batch video generation with exact specs, (7) Brand-consistent production videos with precise control. homepage: https://docs.heygen.com/reference/create-an-avatar-video allowed-tools: mcp__heygen__* metadata: openclaw: requires: env: - HEYGEN_API_KEY primaryEnv: HEYGEN_API_KEY

Avatar Video

Create AI avatar videos with full control over avatars, voices, scripts, and backgrounds using POST /v3/videos. Two creation modes via discriminated union on type:

  • "type": "avatar" + avatar_id β€” use a HeyGen avatar from the library
  • "type": "image" + image (AssetInput) β€” animate any photo via Avatar IV

    • Authentication

    All requests require the X-Api-Key header. Set the HEYGEN_API_KEY environment variable.

    curl -X GET "https://api.heygen.com/v3/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.

    | Task | MCP Tool | Fallback (Direct API) | |------|----------|----------------------| | Check video status / get URL | mcp__heygen__get_video | GET /v3/videos/{video_id} | | List account videos | mcp__heygen__list_videos | GET /v3/videos | | Delete a video | mcp__heygen__delete_video | DELETE /v3/videos/{video_id} |

    Video generation (POST /v3/videos) and avatar/voice listing are done via direct API calls β€” see reference files below.

    Default Workflow

    1. List avatar looks β€” GET /v3/avatars/looks β†’ pick a look, note its id (this is the avatar_id) and default_voice_id. See avatars.md 2. List voices (if needed) β€” GET /v3/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 /v3/videos with avatar_id, voice_id, script, and optional background per scene. See video-generation.md 5. Poll for completion β€” GET /v3/videos/{video_id} until status is completed. See video-status.md

    Routing: This Skill vs Create Video

    This skill = precise control (specific avatar, exact script, custom background). create-video = prompt-based ("make me a video about X", AI handles the rest).

    Reference Files

    Read these as needed β€” they contain endpoint details, request/response schemas, and code examples (curl, TypeScript, Python).

    Core workflow:

  • references/video-generation.md β€” POST /v3/videos request fields, avatar input modes, voice settings, backgrounds
  • references/avatars.md β€” GET /v3/avatars (groups) and GET /v3/avatars/looks (looks β†’ avatar_id)
  • references/voices.md β€” GET /v3/voices with filtering by language, gender, engine
  • references/video-status.md β€” GET /v3/videos/{id} polling patterns and download

    • Customization:

  • references/scripts.md β€” Script writing, SSML break tags, pacing
  • references/backgrounds.md β€” Solid color and image backgrounds
  • references/captions.md β€” Auto-generated captions/subtitles
  • references/text-overlays.md β€” Text overlays with fonts and positioning

    • Advanced:

  • references/photo-avatars.md β€” Animate photos via type: "image" (Avatar IV), AI-generated avatars
  • references/templates.md β€” Template listing and variable replacement
  • references/remotion-integration.md β€” Using HeyGen avatars in Remotion compositions
  • references/webhooks.md β€” Webhook endpoints and events
  • references/assets.md β€” Uploading images, videos, audio
  • references/dimensions.md β€” Resolution and aspect ratios
  • references/quota.md β€” Credit system and usage limits

    • Best Practices

    1. Preview avatars before generating β€” Use GET /v3/avatars/looks and 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

    πŸ“‹ Tips & Best Practices

    1. Preview avatars before generating β€” Use GET /v3/avatars/looks and 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