Index of every page on this site: llms.txt
All skills
heygen-com avatar

/heygen

@1bd5e4d
by HeyGenheygen-com/skills558 stars
92
Run it yourself

HeyGen AI agent skills — avatar creation and video production via the v3 Video Agent pipeline

Use this Skill: https://skilld.dev/gh/heygen-com/skills/heygen

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈26 tokens for metadata: the name and description. ≈1.2k when used: this file.

SKILL.md has missing or invalid fields
  • The name in the SKILL.md header is missing or is not text.
  • The description in the SKILL.md header is missing or is not text.
Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

HeyGen Video Agent — NanoClaw Container Skill

When to Use

Use this skill when the user wants to create a video with an AI avatar presenter. Triggers: "make a video", "create a video message", "record a video", "avatar video", "talking head video", "video pitch", "video update".

NOT for: image generation, audio-only TTS, video translation, or cinematic b-roll.

Required Environment

Steps

Step 1: Discover Available Avatars

heygen avatar list --ownership public --limit 5 | jq '.data[] | {group_id: .id, avatar_name: .name}'

avatar list returns avatar groups — each .id is a group_id, not an avatar_id. The avatar_id you pass to generation is a specific look: list looks with heygen avatar looks list --group-id <group_id> | jq '.data[] | {avatar_id: .id, preview_image_url}' and pick a look's .id. If the user already has a specific look id, use it directly.

Step 2: Find a Voice

heygen voice list --limit 10 | jq '.data[] | {voice_id, name, language}'

Pick a voice_id matching the desired language and tone.

Step 3: Write the Script

Write a spoken-word script for the avatar. Rules:

  • Write for speech, not text. Short sentences. Natural pauses.
  • 150 words per minute is the target pace.
  • 30 seconds = ~75 words. 60 seconds = ~150 words.
  • No stage directions. No markdown. Just what the avatar says.

Step 4: Generate the Video

heygen video-agent create \
  --prompt "YOUR SCRIPT HERE" \
  --avatar-id "AVATAR_ID_HERE" \
  --voice-id "VOICE_ID_HERE" \
  --orientation landscape \
  --wait --timeout 10m

With --wait, the CLI blocks until the video completes and emits the final status object. Without --wait, submission returns immediately — save the session_id from stdout for manual polling.

--timeout 10m is sized for short videos (≤60s). Bump to --timeout 45m for videos >60s or when targeting 2+ minute output — Video Agent generation routinely takes 20-45m for longer clips.

Step 5: Poll for Completion (only without --wait)

heygen video-agent get SESSION_ID | jq '{status: .data.status, video_id: .data.video_id}'

Poll every 15 seconds. Session status is one of thinking, waiting_for_input, reviewing, generating, completed, failed — not a strict linear sequence (waiting_for_input only occurs in chat mode). Terminal states are completed and failed.

Once .data.video_id is present, run heygen video get <video_id> and read .data.video_url for the download URL (and .data.failure_message on failure).

Step 6: Deliver

Download the video and present it to the user:

heygen video download <video_id>

Writes the MP4 to disk and emits {"asset", "message", "path"} on stdout — chain on .path.

Verification

After generating a video, confirm:

  1. CLI exits 0 (generation accepted). Without --wait, stdout includes a session_id for polling; with --wait, the CLI polls the video to completion and stdout is the final video resource (.data.id, .data.video_url).
  2. Polling (or --wait) returns status: "completed" within 5 minutes
  3. heygen video get <video_id> returns a valid HTTPS .data.video_url
  4. Downloaded file is a playable MP4

Report Feedback

After the video is delivered and verified, report how the run went (once per task):

heygen feedback --rating <1-5> --comment "<what worked, or what broke>"

--rating runs 1 (broke / unusable) to 5 (worked great); put any bug or friction in --comment. Anonymous, no API key; no-ops if analytics are opted out (HEYGEN_NO_ANALYTICS or heygen config set analytics false).

Troubleshooting

Symptom Fix
Exit code 3 / auth error on stderr Check heygen auth status; run heygen auth login or set HEYGEN_API_KEY
Exit code 2 / usage error Run heygen video-agent create --help — verify flag names and required args
Status stuck on thinking / generating Wait up to 5 minutes. Videos over 60s take longer.
Missing video_id Session may have failed. Check .data.status; if failed, inspect the full heygen video-agent get <session_id> response for the failure detail.

Limits

  • Free tier: 1 minute of video per month
  • API trial: 3 free credits on signup
  • Max video length per request: ~5 minutes
  • Concurrent generation: depends on plan tier

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

2 warnings8mo4 checks · Risk SAFE
  • Gen Agent Trust Hub8mo

    The HeyGen skill is a secure and well-documented integration for the HeyGen AI video creation API. It correctly manages authentication through environment variables and directs network traffic to official vendor domains (heygen.com, heygen.ai). The skill's capabilities for file system access and processing external data are necessary for its primary function of video asset management and generation, and no malicious patterns or obfuscation techniques were found.

  • Socket8mo

    No alerts

  • Snyk8mo

    Risk: MEDIUM · 1 issue

  • Runlayer8mo

    13/21 files flagged

Signed by skilld at 1bd5e4d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 4 months ago

README badge

README badge for heygen-com/skills/heygen