Skip to main content
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

1

Create a session

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

Poll for status

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

Review and iterate

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

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

​
Session statuses

StatusDescription
thinkingAgent is working (scripting, composing scenes, preparing storyboard).
waiting_for_inputAgent is paused, waiting for your input.
reviewingAgent is paused at a review checkpoint. Review the storyboard and messages.
generatingStoryboard approved — video is rendering.
completedVideo is ready. Retrieve it via GET /v3/videos/{video_id}.
failedSomething 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

ParameterTypeRequiredDescription
promptstringYesInitial message to the agent (1–10,000 characters).
modestringNoSet to "chat" for interactive sessions. Defaults to "generate" (one-shot).
avatar_idstringNoSpecific avatar look ID.
voice_idstringNoSpecific voice ID for narration.
orientationstringNo"landscape" or "portrait". Auto-detected if omitted.
filesarrayNoUp to 20 file attachments (asset_id, url, or base64). See Upload Assets and POST /v3/assets.
auto_proceedbooleanNoIf true, skip interactive review and go straight to video generation. Default: false.
callback_urlstringNoWebhook URL for completion/failure notifications.
callback_idstringNoCaller-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

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

FieldTypeDescription
session_idstringSession identifier.
statusstringCurrent status: thinking, waiting_for_input, reviewing, generating, completed, failed.
progressintegerProgress percentage (0–100).
titlestring | nullAgent-generated session title.
video_idstring | nullVideo ID once generation starts. Use with GET /v3/videos/{video_id}.
created_atintegerUnix timestamp of session creation.
messagesarrayMost recent visible messages (max 40, newest-first).

​
Message object

FieldTypeDescription
rolestring"user" or "model".
contentstringMessage text.
typestring"text", "resource", or "error".
created_atinteger | nullUnix timestamp.
resource_idsarray | nullResource 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

ParameterTypeRequiredDescription
messagestringYesYour message to the agent (1–10,000 characters).
avatar_idstringNoOverride avatar for this message.
voice_idstringNoOverride voice for this message.
filesarrayNoAdditional file attachments (max 20).
auto_proceedbooleanNoIf 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

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

FieldTypeDescription
resource_idstringUnique identifier. Referenced in message resource_ids.
resource_typestringType: image, video, draft, avatar, voice, etc.
source_typestring | null"generated" or "user_uploaded".
urlstring | nullPrimary media URL.
thumbnail_urlstring | nullThumbnail URL.
preview_urlstring | nullPreview URL.
created_atinteger | nullUnix timestamp.
metadataobject | nullType-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"
  }
}