Skip to main content
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.
The most common failure mode for an agent generating a HeyGen video is: read the API reference → write a 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 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:
Then follow the Quick Start: call a model (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.
For agent hosts that support installable skills (Claude Code, Codex, Cursor, OpenClaw, Hermes), install the official heygen-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/videos with model: "heygen-video-1" (HeyGen Video). Use it for scenes with no speaking presenter, and for mascots, animals and stylized characters. Poll GET /v3/models/videos/{video_id} until status is completed.
  • API, a talking video from a photo or video of a person: POST /v3/models/avatars with model: "heygen-avatar-6", the reference and speech audio (HeyGen Avatar 6). For a script, first generate the speech with POST /v3/models/audio/tts and pass its audio_url. A realistic-human reference video needs Enterprise video-reference access and consent (reference media). Poll GET /v3/models/videos/{video_id}.
  • API, the user’s own avatar: POST /v3/videos with type: "avatar", their look, a script and "engine": {"type": "heygen-avatar-6"}, then poll GET /v3/videos/{video_id}.
  • API, Video Agent: POST /v3/video-agents with { "prompt": "<prompt>" }, then poll GET /v3/video-agents/{session_id} until it has a video_id (stop on failed or waiting_for_input), then poll GET /v3/videos/{video_id} until status is completed (1–5 minutes). In production, pass a callback_url and skip polling.
  • CLI: heygen video-agent create --prompt "<prompt>" — JSON output by default, see Output Modes.
  • MCP: call mcp__heygen__create_video_from_avatar or the Video Agent variant.
For prompt structure (scenes, pacing, visual style, casting), see Writing Effective Video Prompts. For visual styles, see Video Agent Styles.

Rules for agents

  • Check auth before writing code. Verify with GET /v3/users/me, heygen auth status, or mcp__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 to POST /v3/videos, Video Agent or templates. Check the input rules before calling: Avatar 6 needs speech audio (generate it from a script with POST /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-After on 429s (Usage Limits), and prefer callback_url in 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