Overview

Generate videos with a single prompt using the Video Agent API. No web app required.

Video Agent is the fastest way to create videos programmatically. Describe what you want in plain text, and the agent handles avatar selection, scripting, scene composition, and production — all in a single API call.

How it works

1. Send a prompt

   POST a text description to /v3/video-agents. Optionally attach files, pick an avatar, or apply a style.

2. Agent produces your video

   The agent writes a script, selects visuals, and renders the video asynchronously. You receive a video_id and session_id immediately.

3. Retrieve the result

   Poll GET /v3/videos/{video_id} until status is completed, then download via video_url. Or use a webhook to get notified automatically.

Authentication

Every request requires either an API key or an OAuth Bearer token:

Header	Value
X-Api-Key	Your HeyGen API key
Authorization	Bearer YOUR_ACCESS_TOKEN (OAuth)

Quick start

curl

curl -X POST "https://api.heygen.com/v3/video-agents" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a 30-second product walkthrough for a new project management app"
  }'

Response

{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_xyz789",
    "created_at": 1711382400
  }
}

Two modes of operation

Video Agent supports two workflows depending on how much control you need:

Mode	Endpoint	Best for
One-shot	POST /v3/video-agents	Fire-and-forget video generation. Send a prompt, get a video.
Interactive session	POST /v3/video-agents/sessions	Review storyboards, send follow-up messages, and iterate before generating.

Both modes support the same file inputs, avatar/voice overrides, and style options. See Video Generation for one-shot details and Interactive Sessions for the multi-turn workflow.

Key concepts

• Session — Every Video Agent request creates a session (session_id). Sessions track the agent’s work: prompt, storyboard, generated assets, and final video.
• Video ID — The video_id returned in the response is used to poll for the final video via GET /v3/videos/{video_id}.
• Styles — Curated visual templates that control scene composition, pacing, and aesthetics. Browse them via GET /v3/video-agents/styles. See Styles & References.
• File attachments — Images, videos, audio, and PDFs you provide as context. The agent uses these as visual references or content sources. See Upload Assets.

Error handling

All Video Agent endpoints return errors in a consistent format:

{
  "error": {
    "code": "invalid_parameter",
    "message": "prompt is required",
    "param": "prompt",
    "doc_url": "https://docs.heygen.com/..."
  }
}

Status	Meaning
400	Invalid request parameters. Check the param field for which field caused the error.
401	Authentication failed. Verify your API key or Bearer token.
429	Rate limit exceeded. Retry after the number of seconds in the Retry-After header.