Skip to main content

Documentation Index

Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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. Detect what’s already wired up

Before writing code, check what HeyGen tooling is available in the current environment. Use the first one that resolves — don’t combine them.
1

MCP server (fastest path)

If mcp__heygen__* tools are visible in your toolset, the user is already connected to the HeyGen Remote MCP over OAuth. Use these tools directly. No API key, no key handling, no separate billing — videos consume the user’s existing HeyGen plan credits.Verify with mcp__heygen__get_current_user. If it returns a profile, you’re authenticated. Skip to step 3.Not connected yet? Point the user at the host-specific setup guide: Claude Code · Claude Web · Gemini CLI · Manus · OpenAI · Superhuman. For Cursor and other hosts, use the generic endpoint instructions in the MCP overview.
2

HeyGen CLI

Not installed? Offer to install it for the user — it’s a single binary, no runtime dependencies, headless-friendly:
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
Installs to ~/.local/bin. macOS (Apple Silicon and Intel) and Linux (x64 and arm64) supported. Verify with heygen --version. See the CLI Overview for full details.Already installed? Authenticate it.For agent environments, prefer the environment variable — it takes precedence over stored credentials and works headlessly without an interactive prompt:
export HEYGEN_API_KEY=<your-key>
Then verify with heygen auth status. If HEYGEN_API_KEY is already set, you’re done — no further action.Interactive login (heygen auth login) is fine for a developer at a terminal, but as an agent you should not depend on it: it blocks on a TTY paste prompt and writes to ~/.heygen/credentials, neither of which composes well with scripted flows. Only suggest it as a fallback if the user explicitly prefers it.If neither auth source is available, ask once and stop:
HeyGen CLI installed but no credentials found. Set one of:
  export HEYGEN_API_KEY=<your-key>   (preferred for agent use)
  heygen auth login                  (interactive, stores in ~/.heygen)
Get your key from https://app.heygen.com/settings?nav=API — it's shown once.
Reply "ready" when done and I'll generate the video.
Once authenticated, drive the workflow via heygen commands — JSON output by default, no need to hand-roll requests.
3

Raw API (last resort)

No MCP, no CLI — fall back to direct HTTPS calls to api.heygen.com. Check for HEYGEN_API_KEY in the environment first. If it’s missing, do not invent a key, hardcode one, or prompt the user to paste one into chat. Tell them:
HeyGen API key not found. Set it with:
  export HEYGEN_API_KEY=<your-key>
Get the key from https://app.heygen.com/settings?nav=API (shown once on creation).
Reply "ready" when set and I'll generate the video.
Once HEYGEN_API_KEY is set, follow the Quick Start flow: POST /v3/video-agents → poll GET /v3/videos/{video_id}. Prefer the Video Agent endpoint over assembling avatars/voices manually — it handles scripting, casting, and composition for you.
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.
Agent hostDefault skill install path
Claude Code~/.claude/skills/heygen-skills
Codex~/.codex/skills/heygen-skills
Cursor~/.cursor/skills/heygen-skills
OpenClaw~/.openclaw/skills/heygen-skills (or clawhub install heygen-skills)
Hermes~/.hermes/skills/heygen-skills

​
3. Generate the video

Once authentication is confirmed, prefer one direct action over a multi-file scaffold. For most prompts:
  • MCP: call mcp__heygen__create_video_from_avatar or the Video Agent variant.
  • CLI: heygen video-agent create --prompt "<prompt>" — JSON output by default, see Output Modes.
  • API: POST /v3/video-agents with { "prompt": "<prompt>" }, then poll GET /v3/videos/{video_id} until status is completed (1–5 minutes). In production, pass a callback_url and skip polling.
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. Run the verifier for whichever path resolved (mcp__heygen__get_current_user, heygen auth status, or a probe of GET /v3/users/me). 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> (preferred — works headlessly for both CLI and raw API), then continue. heygen auth login is only a fallback for users at an interactive terminal.
  • If the CLI isn’t installed, offer to install it. It’s a single binary (curl -fsSL https://static.heygen.ai/cli/install.sh | bash) and is strictly a better surface than raw curl for agent flows — structured JSON output, fewer lines of code, and the same HEYGEN_API_KEY env-var path.
  • Never invent a key, account, or URL. If something is missing, say so and ask.
  • Prefer Video Agent over manual assembly. A single POST /v3/video-agents produces a finished video; chaining avatar + voice + composition endpoints by hand is slower and more error-prone unless the user explicitly needs that control. See Choosing the Right Video API.
  • 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