Who this is for. AI coding agents acting on a user’s behalf — Claude Code, Codex, Cursor, Gemini CLI, Manus, and similar. Humans should start with the Quick Start instead.
curl script → fail at auth → hand the user a “ready-to-run” file that never actually runs. This page exists to make that failure impossible. Detect auth before writing any integration code.
1. Pick a surface: API, then CLI, then MCP
Use the first one that fits. Don’t combine them.1
HeyGen API (default)
Direct HTTPS calls to Then follow the Quick Start: call a model (
api.heygen.com with the key in the X-Api-Key header. Check for HEYGEN_API_KEY in the environment and verify it with GET /v3/users/me. If it’s missing, do not invent a key, hardcode one, or ask the user to paste one into chat. Tell them:POST /v3/models/avatars for HeyGen Avatar 6, or POST /v3/models/videos for HeyGen Video) and poll GET /v3/models/videos/{video_id}.2
HeyGen CLI
For terminal and scripted workflows. Install it if needed (single binary, macOS and Linux):It reads the same
HEYGEN_API_KEY; verify with heygen auth status. Avoid heygen auth login as an agent: it waits on an interactive prompt. Then drive the workflow with heygen commands, which return JSON by default.3
MCP (trial)
If
mcp__heygen__* tools are in your toolset, the user is connected to the HeyGen Remote MCP over OAuth, billed to their subscription credits. Verify with mcp__heygen__get_current_user. Fine for a first few test videos; for anything at scale, move to an API key. If you’re building an app or automation for other users, use an API key.2. Install HeyGen skills (recommended)
For agent hosts that support installable skills (Claude Code, Codex, Cursor, OpenClaw, Hermes), install the officialheygen-com/skills repo. It ships a runtime contract, mode-detection ladder, and producer pipelines for video, avatar creation, and translation — so each new session starts from the same baseline instead of re-deriving it from the API reference.
Agent-facing install guide: INSTALL_FOR_AGENTS.md. Hand the URL to the agent and it will pick the right install path for the host.
3. Generate the video
Once authentication is confirmed, prefer one direct action over a multi-file scaffold. Pick the endpoint by what the user has and wants; llms.txt lists the same routes under “Choose an endpoint”:- API, a clip from a prompt or image:
POST /v3/models/videoswithmodel: "heygen-video-1"(HeyGen Video). Use it for scenes with no speaking presenter, and for mascots, animals and stylized characters. PollGET /v3/models/videos/{video_id}untilstatusiscompleted. - API, a talking video from a photo or video of a person:
POST /v3/models/avatarswithmodel: "heygen-avatar-6", the reference and speech audio (HeyGen Avatar 6). For a script, first generate the speech withPOST /v3/models/audio/ttsand pass itsaudio_url. A realistic-human reference video needs Enterprise video-reference access and consent (reference media). PollGET /v3/models/videos/{video_id}. - API, the user’s own avatar:
POST /v3/videoswithtype: "avatar", their look, a script and"engine": {"type": "heygen-avatar-6"}, then pollGET /v3/videos/{video_id}. - API, Video Agent:
POST /v3/video-agentswith{ "prompt": "<prompt>" }, then pollGET /v3/video-agents/{session_id}until it has avideo_id(stop onfailedorwaiting_for_input), then pollGET /v3/videos/{video_id}untilstatusiscompleted(1–5 minutes). In production, pass acallback_urland skip polling. - CLI:
heygen video-agent create --prompt "<prompt>"— JSON output by default, see Output Modes. - MCP: call
mcp__heygen__create_video_from_avataror the Video Agent variant.
Rules for agents
- Check auth before writing code. Verify with
GET /v3/users/me,heygen auth status, ormcp__heygen__get_current_user, depending on the surface. Don’t write integration code on the assumption that auth will work. - Never ask the user to paste an API key into chat. Direct them to the dashboard, have them
export HEYGEN_API_KEY=<key>, then continue. - Never invent a key, account, or URL. If something is missing, say so and ask.
- Pick the endpoint by input. Raw media (a prompt, a photo, a recording) goes to
/v3/models/*: nothing to set up in HeyGen first, and no avatar or voice-clone slots used. An avatar look, voice clone or template the user already has goes toPOST /v3/videos, Video Agent or templates. Check the input rules before calling: Avatar 6 needs speech audio (generate it from a script withPOST /v3/models/audio/tts), and HeyGen Image needs identity photos plus one reference image. - Polling has a ceiling. Most videos complete in 1–5 minutes. Use exponential backoff, respect
Retry-Afteron429s (Usage Limits), and prefercallback_urlin production. - Don’t hand the user “ready-to-run” scripts as a substitute for actually generating the video. If you’re blocked, name the blocker in one sentence and ask for the one thing you need.
When things break
- Auth errors → API Key guide.
- Video failed (non-2xx, or
status: failedwithfailure_code) → Error Codes. - Rate-limited → Usage Limits.
- Translation, lipsync, avatars, voices → start at the Cookbook overview and follow the per-product card.

