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

# Overview

> Get the lay of the land on the HeyGen developer platform. See what's available across avatars, video agent, translation, streaming, MCP, and SDKs in one.

Video Agent is the fastest way to create videos programmatically. Describe what you want in plain text, and the agent handles avatar selection, scripting, scene composition, and production — all in a single API call.

## How It Works

<Steps>
  <Step title="Send a prompt">
    POST a text description to `POST /v3/video-agents`. Optionally attach files, pick an avatar, or apply a style.
  </Step>

  <Step title="Agent produces your video">
    The agent writes a script, selects visuals, and renders the video asynchronously. You receive a `session_id` immediately, and a `video_id` once generation begins.
  </Step>

  <Step title="Retrieve the result">
    Poll `GET /v3/videos/{video_id}` until `status` is `completed`, then download via `video_url`. Or use a `callback_url` to get notified automatically.
  </Step>
</Steps>

## Quick Start

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.heygen.com/v3/video-agents" \
    -H "X-Api-Key: $HEYGEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Create a 30-second product walkthrough for a new project management app"
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://api.heygen.com/v3/video-agents",
      headers={"X-Api-Key": HEYGEN_API_KEY},
      json={
          "prompt": "Create a 30-second product walkthrough for a new project management app"
      },
  )
  data = resp.json()["data"]
  print(data["session_id"], data["status"])
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch("https://api.heygen.com/v3/video-agents", {
    method: "POST",
    headers: {
      "X-Api-Key": process.env.HEYGEN_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Create a 30-second product walkthrough for a new project management app",
    }),
  });
  const { data } = await resp.json();
  console.log(data.session_id, data.status);
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": null,
    "created_at": 1711382400
  }
}
```

<Note>
  `video_id` is `null` on creation and is populated once the agent begins rendering. Poll `GET /v3/video-agents/{session_id}` to track progress and retrieve the `video_id`.
</Note>

## Two Modes of Operation

Video Agent supports two workflows depending on how much control you need:

| Mode                              | How to use                                    | Best for                                                                                                                   |
| --------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Generate** (`mode: "generate"`) | `POST /v3/video-agents` — default             | Fire-and-forget. Send a prompt, get a video. The agent auto-proceeds through the storyboard.                               |
| **Chat** (`mode: "chat"`)         | `POST /v3/video-agents` with `"mode": "chat"` | Multi-turn interaction. The agent may pause for decisions (e.g. picking a voice), supports revisions and follow-up videos. |

Both modes support the same file inputs, avatar/voice overrides, and style options.

```json Chat mode example theme={null}
{
  "prompt": "Create a product walkthrough for our new app",
  "mode": "chat"
}
```

Use `POST /v3/video-agents/{session_id}` to send follow-up messages, answer the agent's questions, or request revisions in a chat session.

## Processing Time

<Info>
  Video generation is asynchronous. Processing times depend on video length, complexity, and your plan tier.
</Info>

| Factor               | Typical Range                                                       |
| -------------------- | ------------------------------------------------------------------- |
| **Standard plans**   | 5x–10x the final video length (e.g. a 1-min video takes \~5–10 min) |
| **Enterprise plans** | Faster processing with priority queue access                        |
| **Multi-scene**      | Each scene adds to total processing time                            |
| **Peak hours**       | Processing may take longer during high-traffic periods              |

<Warning>
  If a video has been processing for more than 24 hours, something is likely wrong. Contact [HeyGen Support](https://help.heygen.com) with your `video_id`.
</Warning>

**Best practices:**

* Use `callback_url` instead of polling to reduce unnecessary API calls
* Set reasonable poll intervals (10–30 seconds) if polling
* Display a progress indicator to end users based on the 5x–10x benchmark

## Choosing the Right Video API

| Feature              | Video Agent                     | Direct Video (`v3`)    |
| -------------------- | ------------------------------- | ---------------------- |
| **Endpoint**         | `POST /v3/video-agents`         | `POST /v3/videos`      |
| **Input**            | Natural language prompt         | Structured JSON        |
| **Avatar selection** | Agent chooses (or you override) | You specify            |
| **Script writing**   | Agent writes it                 | You write it           |
| **Best for**         | Quick prototypes, simple videos | Programmatic pipelines |
| **Control level**    | Low (prompt-driven)             | High (explicit)        |

<Tip>
  Start with Video Agent. If you need precise control over script, avatar, or timing, use `POST /v3/videos` directly.
</Tip>

## Key Concepts

**Session** — Every Video Agent request creates a session (`session_id`). Sessions track the agent's work: prompt, storyboard, generated assets, and final video. Retrieve session state via `GET /v3/video-agents/{session_id}`.

**Video ID** — The `video_id` is populated once rendering begins. Poll `GET /v3/videos/{video_id}` for status and the final download URL.

**Styles** — Curated visual templates that control scene composition, pacing, and aesthetics. Browse them via `GET /v3/video-agents/styles` and pass a `style_id` to your request.

**File attachments** — Images, videos, audio, and PDFs you provide as context. The agent uses these as visual references or content sources. Pass them via the `files` array as `url`, `asset_id`, or `base64` inputs.

**Incognito mode** — Set `incognito_mode: true` to disable memory injection and extraction for a session.

## Error Handling

All Video Agent endpoints return errors in a consistent format:

```json theme={null}
{
  "error": {
    "code": "invalid_parameter",
    "message": "'prompt' is required and must be 1-10000 characters.",
    "param": "prompt",
    "doc_url": null
  }
}
```

| Status | Meaning                                                                               |
| ------ | ------------------------------------------------------------------------------------- |
| `400`  | Invalid request parameters. Check the `param` field for which field caused the error. |
| `401`  | Authentication failed. Verify your API key or Bearer token.                           |
| `429`  | Rate limit exceeded. Retry after the seconds specified in the `Retry-After` header.   |

For video-specific failures (e.g. rendering errors), check `failure_code` and `failure_message` on the video status response.