> ## 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.

# For ai agents

<Info>
  **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](/docs/quick-start) instead.
</Info>

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.

<Steps>
  <Step title="MCP server (fastest path)">
    If `mcp__heygen__*` tools are visible in your toolset, the user is already connected to the [HeyGen Remote MCP](/mcp/overview) 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](#3-generate-the-video).

    Not connected yet? Point the user at the host-specific setup guide: [Claude Code](/mcp/claude-code) · [Claude Web](/mcp/claude-web) · [Gemini CLI](/mcp/gemini-cli) · [Manus](/mcp/manus) · [OpenAI](/mcp/open-ai) · [Superhuman](/mcp/superhuman). For Cursor and other hosts, use the generic endpoint instructions in the [MCP overview](/mcp/overview).
  </Step>

  <Step title="HeyGen CLI">
    **Not installed?** Offer to install it for the user — it's a single binary, no runtime dependencies, headless-friendly:

    ```bash theme={null}
    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](/cli) 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:

    ```bash theme={null}
    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:

    ```text theme={null}
    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](/commands) — JSON output by default, no need to hand-roll requests.
  </Step>

  <Step title="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:

    ```text theme={null}
    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](/docs/quick-start) flow: `POST /v3/video-agents` → poll `GET /v3/videos/{video_id}`. Prefer the [Video Agent](/docs/video-agent) endpoint over assembling avatars/voices manually — it handles scripting, casting, and composition for you.
  </Step>
</Steps>

## 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. 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](/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](/writing-effective-video-prompts). For visual styles, see [Video Agent Styles](/video-agent-with-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](https://app.heygen.com/settings?nav=API), 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](/docs/choosing-the-right-video-api).
* **Polling has a ceiling.** Most videos complete in 1–5 minutes. Use exponential backoff, respect `Retry-After` on `429`s ([Usage Limits](/docs/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

* Auth errors → [API Key guide](/docs/api-key), [OAuth 2.0](/docs/connecting-your-app-to-heygen-with-oauth-20).
* Video failed (non-2xx, or `status: failed` with `failure_code`) → [Error Codes](/docs/error-codes).
* Rate-limited → [Usage Limits](/docs/usage-limits).
* Translation, lipsync, avatars, voices → start at the [Cookbook overview](/overview) and follow the per-product card.