heygen

Files (6)

• SKILL.md
• client.cjs
• eval.cjs
• heygen.cjs
• index.cjs
• common.cjs · lib/

SKILL.md (first lines)

# 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:

```bash
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:

```bash
node skills/heygen/heygen.cjs --help
```

Plan a request without contacting HeyGen:

```bash
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:

```bash
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:

```bash
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 operator grant:

```bash
node skills/heygen/heygen.cjs http-request translate-video \
  --video-url https://example.com/source.mp4 \
  --output-language de \
  --mode fast \
  --operator-grant
```

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw