Interactive Sessions - HeyGen Documentation

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.

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

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

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

Full schema: POST /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.
`style_id`	string	No	Style ID from `GET /v3/video-agents/styles`. Applies a curated visual template. See Styles & References.
`brand_kit_id`	string	No	Brand kit ID from `GET /v3/brand-kits`. Applies your brand colors, fonts, and logo. See Brand Kits.
`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 and `POST /v3/assets`.
`callback_url`	string	No	Webhook URL for completion/failure notifications.
`callback_id`	string	No	Caller-defined ID echoed back in the webhook payload.
`incognito_mode`	boolean	No	When `true`, disables memory injection and extraction for this session. Default: `false`.

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.

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

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

Response

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

Poll session status

Full schema: GET /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

Full schema: POST /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.
`brand_kit_id`	string	No	Apply a brand kit from this message onward. Lets you switch brands mid-session. See Brand Kits.
`files`	array	No	Additional file attachments (max 20).

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.

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

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

Full schema: GET /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. To list all videos generated by a session, use GET /v3/video-agents/{session_id}/videos.

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

Full schema: POST /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"
  }
}

​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