Documentation Index
Fetch the complete documentation index at: https://developers.heygen.com/llms.txt
Use this file to discover all available pages before exploring further.
This is the one-shot workflow — send a prompt, get a video. For multi-turn collaboration with the agent, see Interactive Sessions. POST https://api.heygen.com/v3/video-agents
session_id to track progress and retrieve the video_id once rendering begins.
Request body
| Parameter | Type | Required | Description |
|---|
prompt | string | Yes | Text description of the video you want (1–10,000 characters). |
avatar_id | string | No | Specific avatar look ID. Omit to let the agent choose automatically. |
voice_id | string | No | Specific voice ID for narration. Omit to let the agent choose automatically. |
style_id | string | No | Style ID from GET /v3/video-agents/styles. Applies a curated visual template. See Styles & References. |
orientation | string | No | "landscape" or "portrait". Auto-detected from content if omitted. |
files | array | No | Up to 20 file attachments. See File input formats below. |
callback_url | string | No | Webhook URL to receive a POST notification on completion or failure. |
callback_id | string | No | Caller-defined ID echoed back in the webhook payload. |
files array uses a type discriminator to specify how the file is provided:
{ "type": "url", "url": "https://example.com/slide-deck.pdf" }
POST /v3/assets to get an asset_id — see Upload Assets.
Example request
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 45-second explainer about our Q3 product launch. Use a friendly, upbeat tone. Include the attached slides as visual context.",
"orientation": "landscape",
"files": [
{ "type": "url", "url": "https://example.com/q3-launch-deck.pdf" }
]
}'
Response
{
"data": {
"session_id": "sess_abc123",
"status": "generating",
"video_id": null,
"created_at": 1711382400
}
}
| Field | Type | Description |
|---|
session_id | string | Primary identifier for this Video Agent session. Use to track progress. |
status | string | Session status: "thinking", "generating", "completed", or "failed". |
video_id | string | null | Video ID for polling via GET /v3/videos/{video_id}. null until rendering begins — poll GET /v3/video-agents/{session_id} to get the video_id once it’s assigned. |
created_at | integer | Unix timestamp of session creation. |
Poll for completion
Video generation is asynchronous. First, poll the session to get the video_id, then poll the video for its final status:
GET https://api.heygen.com/v3/video-agents/{session_id}
GET https://api.heygen.com/v3/videos/{video_id}
curl -X GET "https://api.heygen.com/v3/videos/vid_xyz789" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Response (completed)
{
"data": {
"id": "vid_xyz789",
"title": "Q3 Product Launch Explainer",
"status": "completed",
"video_url": "https://files.heygen.ai/video/vid_xyz789.mp4",
"thumbnail_url": "https://files.heygen.ai/thumb/vid_xyz789.jpg",
"duration": 45.2,
"created_at": 1711382400,
"completed_at": 1711382680
}
}
Video status transitions
The status field progresses through these values:
| Status | Description |
|---|
pending | Video creation request accepted, queued for processing. |
processing | The agent is generating the video. |
completed | Video is ready. video_url contains the download link. |
failed | Generation failed. Check failure_code and failure_message. |
Response fields
| Field | Type | Description |
|---|
id | string | Unique video identifier. |
title | string | null | Video title. |
status | string | Current status: pending, processing, completed, or failed. |
video_url | string | null | Presigned download URL. Present when completed. |
thumbnail_url | string | null | Thumbnail image URL. |
gif_url | string | null | Animated GIF preview URL. |
captioned_video_url | string | null | Video with burned-in captions. |
subtitle_url | string | null | SRT subtitle file download URL. |
duration | number | null | Video duration in seconds. |
created_at | integer | null | Unix timestamp of creation. |
completed_at | integer | null | Unix timestamp when generation finished. |
failure_code | string | null | Machine-readable failure reason. Only when failed. |
failure_message | string | null | Human-readable failure description. Only when failed. |
video_page_url | string | null | Link to the video in the HeyGen app. |
Use webhooks instead of polling
Pass a callback_url in the creation request to receive a POST notification when the video completes or fails, instead of polling:
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 short welcome video for new employees",
"callback_url": "https://your-server.com/webhooks/heygen",
"callback_id": "onboarding-video-001"
}'
callback_id is echoed back in the webhook payload so you can correlate notifications with requests.
List videos
Retrieve all videos in your account with pagination:
GET https://api.heygen.com/v3/videos
| Parameter | Type | Default | Description |
|---|
limit | integer | 10 | Results per page (1–100). |
token | string | — | Opaque cursor from a previous response’s next_token. |
folder_id | string | — | Filter by folder ID. |
title | string | — | Filter by title substring. |
curl "https://api.heygen.com/v3/videos?limit=5" \
-H "X-Api-Key: $HEYGEN_API_KEY"
Delete a video
Permanently remove a video:
DELETE https://api.heygen.com/v3/videos/{video_id}
curl -X DELETE "https://api.heygen.com/v3/videos/vid_xyz789" \
-H "X-Api-Key: $HEYGEN_API_KEY"
{
"data": {
"id": "vid_xyz789",
"deleted": true
}
}
Tips for better results
- Be descriptive in your prompt. Include details about tone, target audience, visual style, and pacing — the agent uses all of this to make better decisions.
- Attach reference files. Pass slides, images, or documents in the
files array to give the agent visual context.
- Use
orientation when you know the target platform (e.g. "portrait" for mobile/social, "landscape" for presentations).
- Apply a style for consistent visual branding across videos. See Styles & References.
- Pin a specific avatar or voice with
avatar_id and voice_id for brand consistency, or omit them to let the agent choose.
