HeyGen

HeyGen

This connector works with HeyGen (AI avatar videos) through the HeyGen API v3 at https://api.heygen.com with the user's own API key: avatars and their looks, voices, talking avatar videos, template videos, prompt-to-video with the Video Agent, video translation with voice cloning and lip-sync, photo avatars, and the account balance.

Spending: making videos, translations and avatars is paid from the HeyGen API balance (pay-as-you-go wallet, or the plan's credits). HeyGen bills video by length and engine; its current prices are on the API dashboard (https://app.heygen.com/developers/api). Before any call that creates something, tell the user what will be made (length, languages, engine) and wait for a yes; heygen_get_account shows what is left. Listing and checking is free.

Setup (about 2 minutes)

1. Sign in at https://app.heygen.com and open the API dashboard: https://app.heygen.com/developers/api.
2. Generate an API key and copy it. API usage is billed separately from a HeyGen web subscription; add balance or a payment method there if the account has none.
3. Paste the key into HEYGEN_API_KEY and install the connector. It is sent as the X-Api-Key header, only to HeyGen. A key restricted to some scopes needs read access to avatars, voices, videos, templates, translations and the user, and write access for the tools that create.

How a video is made

1. Pick a presenter: heygen_list_avatar_groups (characters), then heygen_list_avatar_looks with group_id. The look id is the avatar_id. Pick a voice with heygen_list_voices (or leave it out to use the avatar's default voice).
2. heygen_create_video with avatar_id, script (up to 5,000 characters) and optionally voice_id, aspect_ratio (9:16 for shorts), engine. It returns video_id right away; the video renders in the background.
3. Poll heygen_get_video about every 30 seconds (rendering takes from a minute to several minutes, longer for long scripts). At completed, give the user video_url (MP4), captioned_video_url, subtitle_url and video_page_url. At failed, read failure_message. Download links are signed and expire: call heygen_get_video again for fresh ones.

• Templates: heygen_list_templates, heygen_get_template (variables and their current values), then heygen_generate_from_template with every text variable filled; follow the returned video id with heygen_get_video.
• Video Agent: heygen_create_agent_video with a prompt makes the whole video (script, scenes, avatar). Follow heygen_get_agent_session until it has a video_id, then heygen_get_video.
• Translation: heygen_list_translation_languages, then heygen_translate_video with a public video link and the language names. It returns one id per language; poll heygen_get_video_translation every 30 to 60 seconds. heygen_list_video_translations lists past jobs.
• Photo avatar: heygen_create_photo_avatar with a portrait link (only a person who agreed, such as the user), then heygen_get_avatar_look until status is completed; the look id works in heygen_create_video.
• Library: heygen_list_videos lists finished and running videos; heygen_delete_video is installed switched off.

Engines: avatar_iv is the default; avatar_v gives the most natural motion but only for looks whose supported_api_engines lists it; avatar_iii supports 4K for digital twins and studio avatars but no motion_prompt. Pass it as engine: {"type": "avatar_v"}.

Limits: 10 videos, translations or agent sessions rendering at once on pay-as-you-go (more on Enterprise); 300 list calls and 500 status checks a minute; source files must be public links (video up to 100 MB, audio up to 50 MB and 10 minutes).

Common errors (the reason is in error.code and error.message)

• 401 unauthorized: the key is wrong or revoked.
• 402 insufficient_credit: the balance does not cover this video; the message says how much is needed. usage_limit_reached or trial_limit_exceeded: a workspace or trial limit; an admin or a paid plan lifts it.
• 403 insufficient_api_key_scope: the key is restricted; give it the scopes above.
• 400 invalid_parameter: param names the field (for example an engine the look does not support).
• 404 video_not_found, avatar_not_found, voice_not_found, template_not_found: check the id with the list tools.
• 429 rate_limit_exceeded or quota_exceeded: wait and retry once later, do not loop.

Out of scope here: multi-scene studio videos, image-to-video and prompt video models, lipsync of existing videos, voice cloning and voice design, text to speech on its own, interactive streaming avatars, uploading files (sources must be public links), proofreading translations, webhooks, brand kits and glossaries, folders, batches, and the older v1 and v2 endpoints (retired by HeyGen on 31 October 2026).