---
title: "Create Video Agent Session"
method: POST
path: "/v3/video-agents"
tags: ["Video Agent"]
---

# Create Video Agent Session

`POST /v3/video-agents`

One-shot video generation from a prompt — agent handles scripting, avatar selection, scene composition, and rendering. Supports generate (fire-and-forget) and chat (multi-turn) modes.

## Request body

- CreateVideoAgentRequest — Request body for creating a video from a prompt using Video Agent v3. All configuration is flat (no nested config object). Files use the type-discriminated AssetInput union for flexible asset inputs. Supports two modes: - ``generate`` (default): one-shot — auto-proceeds through storyboard, produces one video. - ``chat``: multi-turn — may pause for user input on real decisions (e.g. pick a voice), auto-proceeds on confirmations. Allows revisions and follow-up videos.
  - `prompt` string, required — The message/prompt for video generation (1-10000 characters)
  - `mode` 'generate' | 'chat'
  - `avatar_id` string, nullable — Specific avatar ID to use
  - `voice_id` string, nullable — Specific voice ID to use for narration
  - `style_id` string, nullable — Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video.
  - `brand_kit_id` string, nullable — Brand kit ID to apply brand colors, fonts, and logos to the generated video.
  - `orientation` 'landscape' | 'portrait', nullable — Video orientation. If not provided, auto-detected from content.
  - `files` union[], nullable — Optional file attachments (max 20 files)
    - union
      - AssetUrl — Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required — Input type discriminator
        - `url` string, required — Publicly accessible HTTPS URL for the asset
      - AssetId — Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required — Input type discriminator
        - `asset_id` string, required — HeyGen asset ID from the asset upload endpoint
      - AssetBase64 — Asset input via base64-encoded content.
        - `type` 'base64', required — Input type discriminator
        - `media_type` string, required — MIME type of the encoded content (e.g. "image/png")
        - `data` string, required — Base64-encoded file content
  - `callback_url` string, nullable — Webhook URL for completion/failure notifications
  - `callback_id` string, nullable — Optional callback ID included in webhook payload
  - `incognito_mode` boolean — When enabled, disables memory injection and extraction for this session

## Response `200`

Successful response

- object
  - `data` CreateVideoAgentResponse — Response from creating a video agent session. Designed as a session resource for future extensibility — GET /v3/video-agents/{session_id} can return the same shape enriched with more fields (messages, video URL, etc.).
    - `session_id` string, required — Session ID — primary identifier for this video agent session
    - `status` 'generating' | 'thinking' | 'completed' | 'failed', required — Session status
    - `video_id` string, nullable — Video ID for polling via GET /v3/videos/{video_id}. Nullable in future multi-turn flows.
    - `created_at` integer, required — Unix timestamp of session creation

## Other responses

- `400` — Invalid request parameters
- `401` — Authentication failed
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/heygen/apis/heygen-external-api.md) · [All operations](https://skmtc.net/heygen/apis/heygen-external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/heygen/heygen-external-api/revisions/e2e54726e210/schema)