/heygen

name: heygen
description: "Prepare guarded HeyGen Direct API requests for avatar video generation, video translation, asset discovery, and status polling."
user-invocable: true
requires:
  bins:
    - node
credentials:
  - id: heygen-api-key
    kind: api_key
    required: true
    secret_ref:
      source: store
      id: HEYGEN_API_KEY
    scope: HeyGen Direct API video generation and translation.
    how_to_obtain: "Create or regenerate the API token from HeyGen account settings. Set `HEYGEN_API_KEY` through browser admin at the active `/admin/secrets` route; if browser admin is unavailable, use `/secret set HEYGEN_API_KEY \"<api-key>\"` in browser `/chat` or TUI; local console fallback: `hybridclaw secret set HEYGEN_API_KEY \"<api-key>\"`."
metadata:
  hybridclaw:
    category: marketing
    short_description: "HeyGen avatar videos and translations through guarded API requests."
    tags:
      - heygen
      - avatar-video
      - video-translation
      - marketing
      - training
    related_roadmap:
      - R55
      - R55.1
    issue: 831
    sub_issue: 874
    stakes_tiers:
      green:
        - avatar-list
        - voice-list
        - language-list
        - video-status
        - translation-status
      amber:
        - video-generate
        - video-translate
      red:
        - public-auto-publish
    escalation:
      writes: confirm-each
      route: f8
    cost_measurement:
      system: UsageTotals
      sub_limit_contract: R5.4
      sub_limit_key: heygen

HeyGen

Use this skill for HeyGen Direct API work: avatar and voice discovery, guarded avatar video generation from approved scripts, video translation with lip-sync, and polling asynchronous generation or translation status.

Scope

• list available avatars, voices, and video-translation target languages
• create gateway-proxied requests for `POST /v2/videos`
• create gateway-proxied requests for `POST /v2/video_translate`
• poll `GET /v1/video_status.get` and `GET /v2/video_translate/{id}`
• classify and retry HeyGen 429, quota, and transient upstream responses with

bounded `Retry-After` aware backoff

• block private or internal media URLs before asking HeyGen to fetch them
• require explicit operator grant before credit-consuming generate/translate calls

Custom avatar training, live streaming, real-time avatars, public publishing, and distribution to external channels are outside this adapter slice.

Credential Rules

HeyGen Direct API uses an API key sent as `X-API-KEY`. Store it in HybridClaw encrypted runtime secrets; never paste it into the prompt.

Recommended setup order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets` and set `HEYGEN_API_KEY`. 2. Browser `/chat` or TUI fallback: `/secret set HEYGEN_API_KEY "<api-key>"`. 3. Local console fallback:

hybridclaw secret set HEYGEN_API_KEY "<api-key>"

For live API calls inside HybridClaw, prefer the helper's `request` command. It sends the secret-backed payload through the local gateway, retries bounded 429/5xx responses, summarizes large asset lists by default, and fails clearly if the gateway truncates a response.

Use `http-request` only when you need to inspect or hand off the generated payload wrapper to the built-in `http_request` tool. The helper sets `secretHeaders: [{ "name": "X-API-KEY", "secretName": "HEYGEN_API_KEY", "prefix": "" }]` so the gateway injects the API key server-side.

Do not try to verify `HEYGEN_API_KEY` with bash, environment inspection, or by asking the model whether the secret exists. The model cannot inspect the gateway secret store. If the operator says the secret was set, attempt the `http_request` call with the emitted `secretHeaders`. Only say the secret is missing if `http_request` returns a gateway error that explicitly says `HEYGEN_API_KEY` is not set, unavailable, missing, or unresolved.

Default Workflow

1. Start with `request list-avatars` and `request list-voices` unless the avatar and voice ids are already known. These commands return concise summaries by default; use `--limit <count>` to show more candidates. Asset ids are opaque values; never use display names as `--avatar-id` or `--voice-id`. 2. Run the script through `/brand-voice` before generating avatar video from marketing, sales, training, or public-facing copy. 3. Use `plan` for natural-language generation or translation requests so the stakes tier and required grant are explicit. 4. Do not emit `generate-video` or `translate-video` requests unless the user has granted that exact credit-consuming operation in the current task or through an approved F8 escalation. 5. Poll status with `request video-status --watch` or `request translation-status --watch`. Use a bounded polling budget, respect `Retry-After`, avoid parallel polling loops, and stop if HeyGen reports quota, credit, or rate-limit failure. 6. Treat auto-publish to public channels as red tier and escalate before any upload, share link, social post, or public channel message.

Command Contract

Run the colocated helper with Node:

node skills/heygen/heygen.cjs --help

Plan a request without contacting HeyGen:

node skills/heygen/heygen.cjs plan "Create an approved onboarding video from this script"

List avatars, voices, or translation languages. Asset lists use compact summary output by default:

node skills/heygen/heygen.cjs request list-avatars --limit 10
node skills/heygen/heygen.cjs request list-voices --limit 10
node skills/heygen/heygen.cjs request list-translation-languages

Generate an avatar video only after explicit operator grant:

node skills/heygen/heygen.cjs http-request generate-video \
  --avatar-id avatar_123 \
  --voice-id voice_123 \
  --script "Approved script text" \
  --title "Quarterly enablement update" \
  --resolution 1080p \
  --aspect-ratio 16:9 \
  --operator-grant

Translate a video only after explicit operato