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

# Interactive Sessions

> Review Video Agent storyboards, send follow-up messages and iterate on a session before it renders.

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

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](https://heygen-1fa696a7.mintlify.site/docs/video-agent.md).

## Session lifecycle

**1. Create a session**

[`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session) with `"mode": "chat"` — Send your initial prompt. The agent begins processing.

**2. Poll for status**

[`GET /v3/video-agents/{session_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-agent-session) — Check progress and read agent messages. The session pauses at `reviewing` status.

**3. Review and iterate**

[`POST /v3/video-agents/{session_id}`](https://heygen-1fa696a7.mintlify.site/reference/send-message-or-request-revision) — Send feedback or approve the storyboard. Repeat as needed.

**4. Generate the video**

Approve the storyboard by sending a confirmation message. The session moves to `generating`, then `completed`. Fetch the final video with [`GET /v3/videos/{video_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video).

### 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}`](https://heygen-1fa696a7.mintlify.site/reference/get-video). |
| `failed` | Something went wrong. Check messages for error details. |

## Create a session

[`POST /v3/video-agents`](https://heygen-1fa696a7.mintlify.site/reference/create-video-agent-session) with `"mode": "chat"`. The rest of the body matches [Prompt to Video](https://heygen-1fa696a7.mintlify.site/docs/video-agent.md#request-body); a `brand_glossary_id` sets pronunciation for the whole session.

> [!TIP]
>
> To skip the review step entirely, create the session with `"mode": "generate"` instead of `"chat"`. It runs straight through to generation and you still get a `session_id` to track. `mode` is the only control over whether the agent pauses — there is no separate flag.

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

The response carries the `session_id`, with `status: "thinking"` and `video_id: null`.

## Poll session status

[`GET /v3/video-agents/{session_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-agent-session) returns the session `status`, `progress` (0–100), an agent-generated `title`, the `video_id` once generation starts, and `messages`: the most recent visible messages (max 40, newest-first). Each message has a `role` (`"user"` or `"model"`), `content`, a `type` (`"text"`, `"resource"`, or `"error"`), and `resource_ids` you can resolve as [session resources](#get-a-session-resource).

## Send a follow-up message

[`POST /v3/video-agents/{session_id}`](https://heygen-1fa696a7.mintlify.site/reference/send-message-or-request-revision) sends feedback, requests changes, or approves the storyboard:

* `message` (1–10,000 characters) is required unless you send an `edit_plan`: scene-scoped edits, one item per scene, built from the scene ids and `edit_version` that [`GET /v3/videos/{video_id}/scenes`](https://heygen-1fa696a7.mintlify.site/reference/get-video-scenes) returns. See [Edit Scenes](https://heygen-1fa696a7.mintlify.site/docs/edit-scenes.md).
* `avatar_id` and `voice_id` override the avatar or voice for this message.
* `brand_kit_id` applies a [brand kit](https://heygen-1fa696a7.mintlify.site/docs/brand-kits.md) from this message onward, so you can switch brands mid-session. The brand glossary stays fixed at session creation.
* `files` adds attachments (max 20).

> [!NOTE]
>
> There is no `auto_proceed` parameter. Sending any follow-up message resumes the agent, so a confirmation like "looks good, generate it" is what approves the storyboard. Both this endpoint and session creation reject unrecognized fields with a `422`.

```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."
  }'
```

Send `"message": "Looks perfect, go ahead and generate the video."` the same way to approve. The response returns the `session_id`, a `run_id`, and the `title`; poll [`GET /v3/video-agents/{session_id}`](https://heygen-1fa696a7.mintlify.site/reference/get-video-agent-session) to see the agent's reply and updated status.

## Get a session resource

Full schema: [`GET /v3/video-agents/{session_id}/resources/{resource_id}`](https://heygen-1fa696a7.mintlify.site/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`](https://heygen-1fa696a7.mintlify.site/reference/list-session-videos).

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

A resource carries its `resource_type` (`image`, `video`, `draft`, `avatar`, `voice`, and more), a `source_type` of `"generated"` or `"user_uploaded"`, and `url`, `thumbnail_url`, and `preview_url` media links.

## Stop a session

Full schema: [`POST /v3/video-agents/{session_id}/stop`](https://heygen-1fa696a7.mintlify.site/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 '{}'
```


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