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

# Prompt to Video

> Create AI avatar videos from a single text prompt with the HeyGen Video Agent API. The agent picks the avatar, voice, and style, then renders in minutes.

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

> [!NOTE]
>
> This is the **one-shot** workflow — send a prompt, get a video. For multi-turn collaboration with the agent, see [Interactive Sessions](https://developers.heygen.com/docs/interactive-sessions.md).

> [!NOTE]
>
> **API reference:** [Create Session](https://developers.heygen.com/reference/create-video-agent-session.md) · [Get Session](https://developers.heygen.com/reference/get-video-agent-session.md) · [List Sessions](https://developers.heygen.com/reference/list-video-agent-sessions.md) · [Stop Session](https://developers.heygen.com/reference/stop-video-agent-session.md) · [Get Video](https://developers.heygen.com/reference/get-video.md) · [List Videos](https://developers.heygen.com/reference/list-videos.md) · [Delete Video](https://developers.heygen.com/reference/delete-video.md)

<video autoPlay loop muted playsInline>
  <source src="https://mintcdn.com/heygen-1fa696a7/G2BUQM52Ic5rbIcR/images/videos/video-agent-launch.mp4?fit=max&auto=format&n=G2BUQM52Ic5rbIcR&q=85&s=e7339e604bb2595bce592f98469c5633" type="video/mp4" />
</video>

Video Agent in 30 seconds.

[`POST /v3/video-agents`](https://developers.heygen.com/reference/create-video-agent-session)

Send a text prompt describing the video you want. The agent handles scripting, avatar selection, scene composition, and rendering. The video is generated asynchronously — use the returned `session_id` to track progress and retrieve the `video_id` once rendering begins.

## Powered by Hyperframes

Video Agent composes and renders its graphics with [Hyperframes](https://developers.heygen.com/hyperframes-overview.md), HeyGen's open-source HTML-to-video framework ([GitHub](https://github.com/heygen-com/hyperframes)). Every animated stat, chart, caption treatment, and scene transition in a generated video is a Hyperframes composition the agent authors to your direction. Because scenes are built in code rather than assembled from a fixed template set, the agent can produce any look you can describe — which is what makes the [style paragraph](https://developers.heygen.com/docs/prompting-guide.md#add-a-style-paragraph) in your prompt so effective. To render your own compositions through the same engine, see [Hyperframes Cloud Rendering](https://developers.heygen.com/hyperframes.md).

### Request body

Only `prompt` (1–10,000 characters) is required; see the [Prompting Guide](https://developers.heygen.com/docs/prompting-guide.md). The [Create Session reference](https://developers.heygen.com/reference/create-video-agent-session.md) lists every field. The ones that shape the result:

* `mode`: `"generate"` (default) runs one-shot; `"chat"` pauses for review and revisions, see [Interactive Sessions](https://developers.heygen.com/docs/interactive-sessions.md).
* `avatar_id`, `voice_id`: pin a look or voice, or omit them to let the agent choose.
* `style_id`: a curated visual template from [`GET /v3/video-agents/styles`](https://developers.heygen.com/reference/list-video-agent-styles), see [Styles & References](https://developers.heygen.com/docs/styles-and-references.md).
* `brand_kit_id`: a [brand kit](https://developers.heygen.com/docs/brand-kits.md) from [`GET /v3/brand-kits`](https://developers.heygen.com/reference/list-brand-kits) applies your colors, fonts, and logo to everything the agent builds.
* `brand_glossary_id`: a [brand glossary](https://developers.heygen.com/docs/brand-glossary.md) from [`GET /v3/brand-glossaries`](https://developers.heygen.com/reference/list-brand-glossaries) sets how custom terms are pronounced; captions and subtitles keep the original spelling.
* `orientation`: `"landscape"` or `"portrait"`, auto-detected when omitted.
* `files`: up to 20 attachments, see below.
* `callback_url`, `callback_id`: a [webhook](#use-webhooks-instead-of-polling) on completion or failure.
* `incognito_mode`: `true` disables memory injection and extraction for the session.

### File input formats

Each item in the `files` array uses a `type` discriminator to specify how the file is provided:

```json URL theme={null}
{ "type": "url", "url": "https://example.com/slide-deck.pdf" }
```

```json Asset ID theme={null}
{ "type": "asset_id", "asset_id": "asset_abc123" }
```

```json Base64 theme={null}
{ "type": "base64", "media_type": "image/png", "data": "iVBORw0KGgo..." }
```

Supported file types: image (png, jpeg), video (mp4, webm), audio (mp3, wav), and pdf. Upload files in advance via [`POST /v3/assets`](https://developers.heygen.com/reference/upload-asset) to get an `asset_id` — see [Upload Assets](https://developers.heygen.com/docs/upload-assets.md).

### Example request

```bash 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 45-second explainer about our Q3 product launch. Use a friendly, upbeat tone. Include the attached slides as visual context.",
    "orientation": "landscape",
    "files": [
      { "type": "url", "url": "https://example.com/q3-launch-deck.pdf" }
    ]
  }'
```

The response carries a `session_id` and a session `status` (`thinking`, `generating`, `completed`, or `failed`). Its `video_id` is `null` until rendering begins.

## Poll for completion

Video generation is asynchronous — processing typically takes 5x–10x the final video length (a 1-minute video takes \~5–10 minutes; enterprise plans get priority queue access). Set poll intervals of 10–30 seconds, or skip polling entirely with a [webhook](#use-webhooks-instead-of-polling). If a video has been processing for more than 24 hours, contact [HeyGen Support](https://help.heygen.com) with your `video_id`.

First, poll the session until it has a `video_id`, then poll the video for its final status. Stop polling the session if its `status` is `failed`, or `waiting_for_input` (the agent needs a reply; answer with [`POST /v3/video-agents/{session_id}`](https://developers.heygen.com/reference/send-message-or-request-revision)).

* [`GET /v3/video-agents/{session_id}`](https://developers.heygen.com/reference/get-video-agent-session) — session status and assigned `video_id`
* [`GET /v3/videos/{video_id}`](https://developers.heygen.com/reference/get-video) — final render status and `video_url`

```python theme={null}
import time, requests

# Step 1: wait for the session to assign a video_id, or stop if it can't
while True:
    sess = requests.get(
        f"https://api.heygen.com/v3/video-agents/{session_id}",
        headers={"X-Api-Key": HEYGEN_API_KEY},
    ).json()["data"]
    if sess["status"] in ("failed", "waiting_for_input"):
        raise RuntimeError(f"Session is {sess['status']}: https://app.heygen.com/video-agent/{session_id}")
    if sess.get("video_id"):
        video_id = sess["video_id"]
        break
    time.sleep(5)

# Step 2: poll video until complete
while True:
    video = requests.get(
        f"https://api.heygen.com/v3/videos/{video_id}",
        headers={"X-Api-Key": HEYGEN_API_KEY},
    ).json()["data"]
    if video["status"] in ("completed", "failed"):
        break
    time.sleep(10)

print(video["video_url"])
```

A completed video carries `video_url`, `thumbnail_url`, `duration`, and `video_page_url`; a failed one carries `failure_code` and `failure_message`. See [Get Video](https://developers.heygen.com/reference/get-video.md) for every field.

## Use webhooks instead of polling

Pass a `callback_url` in the creation request to receive a POST when the video completes or fails. The optional `callback_id` is echoed back in the webhook payload so you can correlate notifications with requests.

To list or permanently remove videos, use [`GET /v3/videos`](https://developers.heygen.com/reference/list-videos) and [`DELETE /v3/videos/{video_id}`](https://developers.heygen.com/reference/delete-video).

## Write a better prompt

The prompt is the whole interface: the agent makes every decision you leave open. The [Prompting Guide](https://developers.heygen.com/docs/prompting-guide.md) builds one real prompt step by step and shows the video it produced.


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