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

# Interactive Sessions

> Build realtime avatar conversations with the HeyGen Interactive Avatar API. Stream live video, low-latency speech, and bidirectional audio over LiveKit-backed.

Interactive sessions give you a multi-turn conversation with the Video Agent. Instead of going straight to rendering, the agent pauses at checkpoints (like storyboard review) so you can provide feedback, adjust direction, and approve before the final video is generated. For the fire-and-forget alternative, see [Prompt to Video](/docs/video-agent).

## Session lifecycle

<Steps>
  <Step title="Create a session">
    [`POST /v3/video-agents`](/reference/create-video-agent-session) with `"mode": "chat"` — Send your initial prompt. The agent begins processing.
  </Step>

  <Step title="Poll for status">
    [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) — Check progress and read agent messages. The session pauses at `reviewing` status.
  </Step>

  <Step title="Review and iterate">
    [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision) — Send feedback or approve the storyboard. Repeat as needed.
  </Step>

  <Step title="Generate the video">
    Send a message with `auto_proceed: true` or approve the storyboard. The session moves to `generating`, then `completed`. Fetch the final video with [`GET /v3/videos/{video_id}`](/reference/get-video).
  </Step>
</Steps>

### Session statuses

| Status              | Description                                                                          |
| ------------------- | ------------------------------------------------------------------------------------ |
| `thinking`          | Agent is working (scripting, composing scenes, preparing storyboard).                |
| `waiting_for_input` | Agent is paused, waiting for your input.                                             |
| `reviewing`         | Agent is paused at a review checkpoint. Review the storyboard and messages.          |
| `generating`        | Storyboard approved — video is rendering.                                            |
| `completed`         | Video is ready. Retrieve it via [`GET /v3/videos/{video_id}`](/reference/get-video). |
| `failed`            | Something went wrong. Check messages for error details.                              |

## Create a session

Full schema: [`POST /v3/video-agents`](/reference/create-video-agent-session). Pass `"mode": "chat"` to enable interactive mode.

### Request body

| Parameter      | Type    | Required | Description                                                                                                                                       |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`       | string  | **Yes**  | Initial message to the agent (1–10,000 characters).                                                                                               |
| `mode`         | string  | No       | Set to `"chat"` for interactive sessions. Defaults to `"generate"` (one-shot).                                                                    |
| `avatar_id`    | string  | No       | Specific avatar look ID.                                                                                                                          |
| `voice_id`     | string  | No       | Specific voice ID for narration.                                                                                                                  |
| `orientation`  | string  | No       | `"landscape"` or `"portrait"`. Auto-detected if omitted.                                                                                          |
| `files`        | array   | No       | Up to 20 file attachments (asset\_id, url, or base64). See [Upload Assets](/docs/upload-assets) and [`POST /v3/assets`](/reference/upload-asset). |
| `auto_proceed` | boolean | No       | If `true`, skip interactive review and go straight to video generation. Default: `false`.                                                         |
| `callback_url` | string  | No       | [Webhook](/docs/webhooks) URL for completion/failure notifications.                                                                               |
| `callback_id`  | string  | No       | Caller-defined ID echoed back in the webhook payload.                                                                                             |

<Tip>
  Set `auto_proceed: true` to skip the review step entirely — the session behaves like the one-shot mode but you still get a `session_id` to track.
</Tip>

### Example

<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 2-minute onboarding video for new engineering hires. Cover team culture, dev tools, and first-week checklist.",
      "mode": "chat",
      "orientation": "landscape"
    }'
  ```

  ```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 2-minute onboarding video for new engineering hires.",
          "mode": "chat",
          "orientation": "landscape",
      },
  )
  session = resp.json()["data"]
  session_id = session["session_id"]
  ```
</CodeGroup>

### Response

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

## Poll session status

Full schema: [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session). Returns the current session status, progress percentage, chat messages, and the `video_id` once generation starts.

### Response

```json theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "reviewing",
    "progress": 45,
    "title": "Engineering Onboarding Video",
    "video_id": null,
    "created_at": 1711382400,
    "messages": [
      {
        "role": "model",
        "content": "I've drafted a storyboard with 4 scenes covering team culture, dev environment setup, key tools, and the first-week checklist. Would you like to review it or should I proceed?",
        "type": "text",
        "created_at": 1711382450,
        "resource_ids": ["res_storyboard_001"]
      },
      {
        "role": "user",
        "content": "Create a 2-minute onboarding video for new engineering hires.",
        "type": "text",
        "created_at": 1711382400,
        "resource_ids": null
      }
    ]
  }
}
```

### Response fields

| Field        | Type           | Description                                                                                        |
| ------------ | -------------- | -------------------------------------------------------------------------------------------------- |
| `session_id` | string         | Session identifier.                                                                                |
| `status`     | string         | Current status: `thinking`, `waiting_for_input`, `reviewing`, `generating`, `completed`, `failed`. |
| `progress`   | integer        | Progress percentage (0–100).                                                                       |
| `title`      | string \| null | Agent-generated session title.                                                                     |
| `video_id`   | string \| null | Video ID once generation starts. Use with [`GET /v3/videos/{video_id}`](/reference/get-video).     |
| `created_at` | integer        | Unix timestamp of session creation.                                                                |
| `messages`   | array          | Most recent visible messages (max 40, newest-first).                                               |

### Message object

| Field          | Type            | Description                                                                                                                 |
| -------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `role`         | string          | `"user"` or `"model"`.                                                                                                      |
| `content`      | string          | Message text.                                                                                                               |
| `type`         | string          | `"text"`, `"resource"`, or `"error"`.                                                                                       |
| `created_at`   | integer \| null | Unix timestamp.                                                                                                             |
| `resource_ids` | array \| null   | Resource IDs resolvable via [`GET /v3/video-agents/{session_id}/resources/{resource_id}`](/reference/get-session-resource). |

## Send a follow-up message

Full schema: [`POST /v3/video-agents/{session_id}`](/reference/send-message-or-request-revision). Send feedback, request changes, or approve the storyboard. The agent processes your message and updates the session.

### Request body

| Parameter      | Type    | Required | Description                                                                                  |
| -------------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| `message`      | string  | **Yes**  | Your message to the agent (1–10,000 characters).                                             |
| `avatar_id`    | string  | No       | Override avatar for this message.                                                            |
| `voice_id`     | string  | No       | Override voice for this message.                                                             |
| `files`        | array   | No       | Additional file attachments (max 20).                                                        |
| `auto_proceed` | boolean | No       | If `true`, skip remaining review steps and generate the video immediately. Default: `false`. |

### Example: Request changes

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents/sess_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Looks great, but add a scene about our code review process before the checklist scene."
  }'
```

### Example: Approve and generate

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents/sess_abc123" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Looks perfect, go ahead and generate the video.",
    "auto_proceed": true
  }'
```

### Response

```json theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "run_id": "run_def456",
    "title": "Engineering Onboarding Video"
  }
}
```

After sending a message, poll [`GET /v3/video-agents/{session_id}`](/reference/get-video-agent-session) to see the agent's response and updated status.

## Get a session resource

Full schema: [`GET /v3/video-agents/{session_id}/resources/{resource_id}`](/reference/get-session-resource). Retrieve a specific resource by ID — storyboard images, draft videos, selected avatars, and voices are all exposed as resources. Resource IDs are referenced in message `resource_ids` arrays. To list all videos generated by a session, use [`GET /v3/video-agents/{session_id}/videos`](/reference/list-session-videos).

### Example

```bash theme={null}
curl "https://api.heygen.com/v3/video-agents/sess_abc123/resources/res_storyboard_001" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
```

### Response

```json theme={null}
{
  "data": {
    "resource_id": "res_storyboard_001",
    "resource_type": "image",
    "source_type": "generated",
    "url": "https://files.heygen.ai/resources/res_storyboard_001.png",
    "thumbnail_url": "https://files.heygen.ai/resources/res_storyboard_001_thumb.png",
    "created_at": 1711382450,
    "metadata": {}
  }
}
```

### Resource object

| Field           | Type            | Description                                              |
| --------------- | --------------- | -------------------------------------------------------- |
| `resource_id`   | string          | Unique identifier. Referenced in message `resource_ids`. |
| `resource_type` | string          | Type: `image`, `video`, `draft`, `avatar`, `voice`, etc. |
| `source_type`   | string \| null  | `"generated"` or `"user_uploaded"`.                      |
| `url`           | string \| null  | Primary media URL.                                       |
| `thumbnail_url` | string \| null  | Thumbnail URL.                                           |
| `preview_url`   | string \| null  | Preview URL.                                             |
| `created_at`    | integer \| null | Unix timestamp.                                          |
| `metadata`      | object \| null  | Type-specific metadata.                                  |

## Stop a session

Full schema: [`POST /v3/video-agents/{session_id}/stop`](/reference/stop-video-agent-session). Stop an in-progress agent run — the agent halts at the next checkpoint, and partial results are preserved.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/video-agents/sess_abc123/stop" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json Response theme={null}
{
  "data": {
    "session_id": "sess_abc123"
  }
}
```