> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# For AI Agents

> Agent-first onboarding for AI coding agents — detect auth before writing code, use the API first, then the CLI, then MCP, and go from a blank session to a finished video.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-9.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=9afc7a8acf73c8f9ec670dde494e9931)

> [!NOTE]
>
> **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](https://heygen-1fa696a7.mintlify.site/docs/quick-start.md) 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:

```text theme={null}
HeyGen API key not found. Set it with:
  export HEYGEN_API_KEY=<your-key>
Get the key from https://platform.heygen.com/api-keys (shown once on creation).
Reply "ready" when set and I'll generate the video.
```

Then follow the [Quick Start](https://heygen-1fa696a7.mintlify.site/docs/quick-start.md): call a model (`POST /v3/models/avatars` for [HeyGen Avatar 6](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md), or `POST /v3/models/videos` for [HeyGen Video](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md)) 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):

```bash theme={null}
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
```

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](https://heygen-1fa696a7.mintlify.site/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](https://heygen-1fa696a7.mintlify.site/mcp/overview.md) 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 official [`heygen-com/skills`](https://github.com/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`](https://github.com/heygen-com/skills/blob/master/INSTALL_FOR_AGENTS.md). Hand the URL to the agent and it will pick the right install path for the host.

| Agent host | Default 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. Pick the endpoint by what the user has and wants; [llms.txt](https://heygen-1fa696a7.mintlify.site/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](https://heygen-1fa696a7.mintlify.site/docs/models/heygen-video.md)). 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](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md)). 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](https://heygen-1fa696a7.mintlify.site/docs/models/avatar-6.md#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](https://heygen-1fa696a7.mintlify.site/output-modes.md).
* **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](https://heygen-1fa696a7.mintlify.site/writing-effective-video-prompts). For visual styles, see [Video Agent Styles](https://heygen-1fa696a7.mintlify.site/video-agent-with-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](https://platform.heygen.com/api-keys), 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 `429`s ([Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md)), 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

* Auth errors → [API Key guide](https://heygen-1fa696a7.mintlify.site/docs/api-key.md).
* Video failed (non-2xx, or `status: failed` with `failure_code`) → [Error Codes](https://heygen-1fa696a7.mintlify.site/docs/error-codes.md).
* Rate-limited → [Usage Limits](https://heygen-1fa696a7.mintlify.site/docs/usage-limits.md).
* Translation, lipsync, avatars, voices → start at the [Cookbook overview](https://heygen-1fa696a7.mintlify.site/overview) and follow the per-product card.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.