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":"[Truncated]","amber":"[Truncated]","red":"[Truncated]"},"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 . Only say the secret is missing if returns a gateway error that explicitly says is not set, unavailable, missing, or unresolved.