---
title: "Create a video from a prompt"
method: POST
path: "/v1/video_agent/generate"
tags: ["Video Agent"]
---

# Create a video from a prompt

`POST /v1/video_agent/generate`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v1/video_agent/generate`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Creates a video from a text prompt with Video Agent, which picks the avatar, writes the script and produces the video. Runs asynchronously: poll GET /v2/videos/{video_id} with the returned video_id.

## Request body

- ExternalCreateVideoAgentSessionRequest: Request body for creating a video from a prompt using Video Agent V2A.
  - `prompt` string, required: The message/prompt for video generation (1-10000 characters)
  - `avatar_id` string, nullable: Specific avatar ID to use
  - `voice_id` string, nullable: Specific voice ID to use for narration
  - `orientation` 'landscape' | 'portrait', nullable: Video orientation. If not provided, auto-detected from content.
  - `duration_sec` integer, nullable: Approximate video duration in seconds (minimum 5)
  - `config` VideoAgentConfig: Configuration options for video generation.
    - `duration_sec` integer, nullable: Approximate video duration in seconds (minimum 5)
    - `orientation` 'landscape' | 'portrait', nullable: Video orientation. If not provided, auto-detected from content.
    - `avatar_id` string, nullable: Specific avatar ID to use
    - `voice_id` string, nullable: Specific voice ID to use for narration
  - `files` FileInput[], nullable: Optional file attachments (max 20 files)
    - `asset_id` string, required: HeyGen asset ID (from /v1/asset upload endpoint). Supported types: image (png, jpeg), video (mp4, webm), pdf.
  - `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
  - `error` object, nullable
  - `data` ExternalCreateVideoAgentSessionResponse: Response from creating a video.
    - `video_id` string, required: Video ID. Use with GET /v2/videos/{video_id} for polling
    - `session_id` string, required: Video Agent session ID

## Other responses

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

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v1/video_agent/generate/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)