Interactive Sessions

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.

Session lifecycle

Create a session

POST /v3/video-agents with "mode": "chat" — Send your initial prompt. The agent begins processing.

Poll for status

GET /v3/video-agents/{session_id} — Check progress and read agent messages. The session pauses at reviewing status.

Review and iterate

POST /v3/video-agents/{session_id} — Send feedback or approve the storyboard. Repeat as needed.

Generate the video

Send a message with auto_proceed: true or approve the storyboard. The session moves to generating, then completed.

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}`.
`failed`	Something went wrong. Check messages for error details.

Create a session

POST https://api.heygen.com/v3/video-agents

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.
`auto_proceed`	boolean	No	If `true`, skip interactive review and go straight to video generation. Default: `false`.
`callback_url`	string	No	Webhook URL for completion/failure notifications.
`callback_id`	string	No	Caller-defined ID echoed back in the webhook payload.

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.

Example

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

Response

{
  "data": {
    "session_id": "sess_abc123",
    "status": "thinking",
    "video_id": null,
    "created_at": 1711382400
  }
}

Poll session status

GET https://api.heygen.com/v3/video-agents/{session_id}

Returns the current session status, progress percentage, chat messages, and the video_id once generation starts.

Response

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

Send a follow-up message

POST https://api.heygen.com/v3/video-agents/{session_id}

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

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

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

{
  "data": {
    "session_id": "sess_abc123",
    "run_id": "run_def456",
    "title": "Engineering Onboarding Video"
  }
}

After sending a message, poll GET /v3/video-agents/{session_id} to see the agent’s response and updated status.

Get a session resource

GET https://api.heygen.com/v3/video-agents/{session_id}/resources/{resource_id}

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.

Example

curl "https://api.heygen.com/v3/video-agents/sess_abc123/resources/res_storyboard_001" \
  -H "X-Api-Key: $HEYGEN_API_KEY"

Response

{
  "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

POST https://api.heygen.com/v3/video-agents/{session_id}/stop

Stop an in-progress agent run. The agent halts at the next checkpoint, and partial results are preserved.

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 '{}'

Response

{
  "data": {
    "session_id": "sess_abc123"
  }
}

Auth

User Info

Pricing

Video Agent

Video Generation

Video Translation

Avatars

Voices

Lipsync

Webhook

Assets

Integrations

Legacy APIs

Limits

Session lifecycle

Session statuses

Create a session

Request body

Example

Response

Poll session status

Response

Response fields

Message object

Send a follow-up message

Request body

Example: Request changes

Example: Approve and generate

Response

Get a session resource

Example

Response

Resource object

Stop a session

Auth

User Info

Pricing

Video Agent

Video Generation

Video Translation

Avatars

Voices

Lipsync

Webhook

Assets

Integrations

Legacy APIs

Limits

Documentation Index

​Session lifecycle

​Session statuses

​Create a session

​Request body

​Example

​Response

​Poll session status

​Response

​Response fields

​Message object

​Send a follow-up message

​Request body

​Example: Request changes

​Example: Approve and generate

​Response

​Get a session resource

​Example

​Response

​Resource object

​Stop a session

Session lifecycle

Session statuses

Create a session

Request body

Example

Response

Poll session status

Response

Response fields

Message object

Send a follow-up message

Request body

Example: Request changes

Example: Approve and generate

Response

Get a session resource

Example

Response

Resource object

Stop a session