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

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

Create a session

POST /v3/video-agents with "mode": "chat". The rest of the body matches Prompt to Video; a brand_glossary_id sets pronunciation for the whole session.
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.
The response carries the session_id, with status: "thinking" and video_id: null.

Poll session status

GET /v3/video-agents/{session_id} 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.

Send a follow-up message

POST /v3/video-agents/{session_id} 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 returns. See Edit Scenes.
  • avatar_id and voice_id override the avatar or voice for this message.
  • brand_kit_id applies a brand kit from this message onward, so you can switch brands mid-session. The brand glossary stays fixed at session creation.
  • files adds 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.
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} to see the agent’s reply 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.
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. Stop an in-progress agent run — the agent halts at the next checkpoint, and partial results are preserved.