HEheygen
Video Agent

Create Video Agent Session

Changed on

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.

post/v3/video-agents

Request

  • Base URL
    https://api.heygen.com
  • URL
    https://api.heygen.com/v3/video-agents
  • Auth
    • API key in header x-api-key
    • or HTTP bearer

Request body

promptstring required

The message/prompt for video generation (1-10000 characters)

mode'generate' | 'chat'
avatar_idstring nullable

Specific avatar ID to use

voice_idstring nullable

Specific voice ID to use for narration

style_idstring nullable

Style ID from GET /v3/video-agents/styles. Applies a curated visual template to the generated video.

brand_kit_idstring nullable

Brand kit ID to apply brand colors, fonts, and logos to the generated video. In enterprise workspaces with a locked brand policy, only the workspace default brand kit is accepted; omit this field to apply the workspace default automatically.

brand_glossary_idstring nullable

Brand glossary ID controlling how custom terms are pronounced in the generated video's narration (for example, saying 'HeyGen' as 'hey-jen'). Pronunciation is applied to the synthesized audio only, so caption and subtitle text still show the original script wording. Discover IDs via GET /v3/brand-glossaries.

orientation'landscape' | 'portrait' nullable

Video orientation. If not provided, auto-detected from content.

callback_urlstring nullable

Webhook URL for completion/failure notifications

callback_idstring nullable

Optional callback ID included in webhook payload

visibility'private' | 'space' | 'selected'

Who can open the session. private: the owner only. space: everyone in the workspace can open and drive the session. selected: the owner plus the workspace members listed in members. Defaults to space. Applies to the session and its conversation; does not change existing sessions.

membersstring[] nullable

Email addresses to grant access to. Valid only with visibility: selected, and every address must belong to a member of the caller's workspace (max 100). May be omitted or empty, leaving the session owner-only until members are added.

incognito_modeboolean

When enabled, disables memory injection and extraction for this session

Response

Successful response

Example response

{
  "data": {
    "session_id": "sess_012abc345def678",
    "status": "generating",
    "video_id": "v_abc123def456",
    "created_at": 1711929600
  }
}

Changes

  • 7dfa5e59b4f5Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added asset_id base64 url discriminator mapping keys to the // request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status