Skip to main content
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:
HeaderValue
X-Api-KeyYour HeyGen API key
AuthorizationBearer YOUR_ACCESS_TOKEN (OAuth)

​
Quick start

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:
ModeEndpointBest for
One-shotPOST /v3/video-agentsFire-and-forget video generation. Send a prompt, get a video.
Interactive sessionPOST /v3/video-agents/sessionsReview 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/..."
  }
}
StatusMeaning
400Invalid request parameters. Check the param field for which field caused the error.
401Authentication failed. Verify your API key or Bearer token.
429Rate limit exceeded. Retry after the number of seconds in the Retry-After header.