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.
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 anedit_plan: scene-scoped edits, one item per scene, built from the scene ids andedit_versionthatGET /v3/videos/{video_id}/scenesreturns. See Edit Scenes.avatar_idandvoice_idoverride the avatar or voice for this message.brand_kit_idapplies a brand kit from this message onward, so you can switch brands mid-session. The brand glossary stays fixed at session creation.filesadds 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."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.
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.

