heygen

name	heygen
description	Agent-callable HeyGen tools — generate AI avatar videos, translate and lip-sync videos, synthesize speech, and clone or browse voices and avatars. Use when the user mentions HeyGen or wants to create, translate, or check the status of AI videos, or to generate or clone a voice — including requests that don't name HeyGen, e.g. make an avatar video from a script, translate a video to Spanish, turn a script into a voiceover, or clone a voice from a recording.
license	Elastic-2.0
compatibility	Run `npm install --omit=dev` in this directory, then `node cli.js`. The TypeScript source needs Node.js 22.18+; on older Node, run `cli.js` for build-it-yourself / prebuilt / alternative-runtime options.
metadata	{"source":"https://github.com/zapier/connectors/blob/main/apps/heygen/SKILL.md","title":"Heygen","api-docs":"https://developers.heygen.com","zapier-app-key":"HeyGenCLIAPI"}

Heygen

Agent-callable tools for HeyGen's AI video platform, over the public HeyGen v3 API (https://api.heygen.com). Generate AI avatar videos from a script or audio, generate short cinematic clips from a prompt, translate and lip-sync existing videos, drive the prompt-to-video Video Agent, synthesize speech, and browse the avatars and voices those jobs need. Video generation is asynchronous: a create tool returns an id, and you poll the matching get* tool until the job is completed and its result URLs appear.

Independent, unofficial connector for Heygen. Not affiliated with, endorsed by, or sponsored by Heygen. "Heygen" is a trademark of its owner, used only to identify the service this connector works with.

When to use this

• Create AI videos — an avatar (or animated image) speaking a script (createVideo), a short prompt-driven cinematic clip (createCinematicVideo), or a fully agent-authored video from a text prompt (createVideoAgentVideo).
• Transform existing videos — translate into other languages (translateVideo) or replace the audio and re-sync the lips (createLipsync).
• Synthesize speech and pick voices/avatars — text-to-speech (generateSpeech), and browse/clone/design voices and browse avatar looks to resolve the ids the create tools need.
• Track async jobs and account state — poll a video/translation/lipsync/session by id, list past jobs, and check remaining credits (getCurrentUser) before generating.

Setup

This is an agentskills.io skill.

If the connector has not been installed as a skill yet, install it first with npx skills add zapier/connectors --skill heygen (or your harness's own skill-install mechanism), then continue here. Installing the skill copies these files, not dependencies. Before running the CLI, a local MCP server, or zapier-sdk auth commands, run npm install --omit=dev here once. Importing the published package as a dependency in your own project instead? That npm install already resolves everything — see references/use-as-sdk.md.

Want the actual repo source instead — to browse references/, run this connector's tests, or hack on it? See README.md for a scoped git clone.

The connector runs on Node.js 22.18+. Pick the reference that matches how you're running it, and load it before doing anything else:

You have...	Load
An MCP-aware client — tools may already be loaded (e.g. mcp__heygen__<tool>), or you can register a local server yourself (or guide the user to)	references/use-as-mcp.md
Terminal / subprocess access (you can run node)	references/use-as-cli.md
Only your own code, importing this package as a dependency	references/use-as-sdk.md
No tool access, no terminal, no ability to import this package — you write your own code that calls the Heygen API directly (e.g. a code-execution sandbox)	references/use-as-recipe.md

Scripts

All scripts use the single heygen connection. Generate tools are asynchronous — pair each with its poll tool (e.g. createVideo → getVideo).

Script	Script name	Connections	Description
scripts/createVideo.ts	createVideo	heygen	Generate an avatar or image video from a script or audio; returns a video_id to poll with getVideo.
scripts/createCinematicVideo.ts	createCinematicVideo	heygen	Generate a short (4–15s) cinematic clip from a prompt and 1–3 avatar looks.
scripts/getVideo.ts	getVideo	heygen	Poll a video's status and, once complete, get its result URLs (video, thumbnail, captions, share page).
scripts/listVideos.ts	listVideos	heygen	List videos in the account, filterable by folder or title.
scripts/deleteVideo.ts	deleteVideo	heygen	Permanently delete a video and its files.
scripts/generateSpeech.ts	generateSpeech	heygen	Synthesize speech audio from text (TTS) using a starfish-compatible voice.
scripts/listVoices.ts	listVoices	heygen	List voices; filter by type, engine, language, or gender. Resolver for voice_id.
scripts/designVoice.ts	designVoice	heygen	Generate candidate voices from a natural-language description.
scripts/cloneVoice.ts	cloneVoice	heygen	Clone a voice from a reference audio file; poll readiness with getVoice.
scripts/getVoice.ts	getVoice	heygen	Get one voice's details and clone/training status by id.
scripts/listAvatarLooks.ts	listAvatarLooks	heygen

Disambiguation & refusals

• Resolve ids before generating; act on a single match. The create tools take ids, not names — get an avatar_id from listAvatarLooks, a voice_id from listVoices, a video_id from listVideos. If a described avatar/voice/video has exactly one match, use it; if two or more tie on the described name/title, list the candidates with a distinguishing field (avatar type, language, created time) and ask which — don't silently pick.
• Don't fake unsupported jobs. This connector does not support: multi-scene "Studio" videos (per-scene avatars/backgrounds in one video), template-based video generation, uploading local asset files (pass a public HTTPS URL to *_url inputs instead), or photo-avatar/digital-twin training pipelines beyond createAvatar's entry point. If asked for one of these, say it isn't supported — don't substitute a different tool and report success for something you didn't do.
• Generation is async and consumes credits. A create call returning an id is not a finished video — poll the get* tool until completed. Failed or in-progress jobs can still consume credits; getCurrentUser reports the remaining balance.

Auth

Every shape passes auth as one connection selector, not the secret — a [<resolver>:]<value> string. Every connector accepts zapier:<connection-id> (Zapier-managed auth — routes through Zapier's auth, retries, and governance layer); some also accept one or more direct-token resolvers (naming and count vary per connector) — check this connector's own resolvers rather than assuming. The <resolver>: prefix is optional; a bare value goes to the first resolver that claims it — a UUID-shaped bare value always claims zapier:. Each script declares the connections it needs and the resolvers each accepts. The exact syntax for passing a connection (and how to see this connector's resolver list) differs by shape — see the reference you loaded above.

Checking what's already configured first? Don't dump environment values to do it — env or env | grep <name> prints the value along with the name, leaking a live credential into the transcript if one is set. Check names only (env | cut -d= -f1 | grep -i <name>) or test a known name directly ([ -n "$VAR_NAME" ]).

Two connection resolvers use different credentials and bill differently: env:HEYGEN_API_KEY (direct — a long-lived API key from the HeyGen dashboard, sent as X-Api-Key, bills the API tier) vs zapier:<connection-id> (Zapier-managed — routes through the connected account's OAuth credential, bills the account's web subscription plan). Both paths are verified. Read the balance field matching your auth path (wallet vs subscription — see references/heygen-api-gotchas.md) before a generate call, to avoid an insufficient_credit failure mid-flow.

No connection yet? Pick one — and follow the reference's own flow to obtain it; never just ask the user for a connection id or token as if they already have one memorized:

	Load
Pass the credential directly	references/use-without-zapier.md
Route it through a Zapier connection	references/use-with-zapier.md

Output format

Every script returns a { data, meta } envelope:

• data — the script's result (the shape its outputSchema declares; see the reference you loaded above for how to inspect a script's exact schema in your shape).
• meta.outputDataValidation — what validating data did:
  • { skipped: false, droppedPaths: null } — validated, nothing removed.
  • { skipped: false, droppedPaths: [...], instruction } — validated, but those paths were stripped from data: fields the script returned from the API that the outputSchema doesn't declare. If you need them, re-run with output validation skipped.
  • { skipped: true } — validation was bypassed; data is the raw, unchecked script output.

Reading dropped fields / skipOutputDataValidation. To receive the raw, unvalidated result, opt out of output validation (the exact syntax differs by shape — see the reference you loaded above). Input validation is never skipped.

Trimming the result / filterOutputData. To shrink a large result down to the fields you need, pass a jq expression that post-processes data (again, exact syntax per shape). The jq runs against data only, NOT the { data, meta } envelope, so write it rooted at data (run the script's --help — or your shape's equivalent — to see its output schema). The transformed value replaces data, meta is preserved, and the result is NOT re-validated against the output schema.

References

Reference	Load when
heygen-api-gotchas.md	Before building a HeyGen flow — async create→poll model, status enums, presigned-URL expiry, error codes, rate limits/concurrency, credits/billing, pagination, and per-domain rules (voices/TTS, avatars, cinematic, translation, lipsync, video agent).
use-as-recipe.md	Loaded by a harness writing its own code against the vendor API (can't load the tools / run the CLI / import the package) — request patterns, response shapes, and pointers into the gotchas.