Skip to main content
This is the one-shot workflow — send a prompt, get a video. For multi-turn collaboration with the agent, see Interactive Sessions.
API reference: Create Session · Get Session · List Sessions · Stop Session · Get Video · List Videos · Delete Video
POST /v3/video-agents Send a text prompt describing the video you want. The agent handles scripting, avatar selection, scene composition, and rendering. The video is generated asynchronously — use the returned session_id to track progress and retrieve the video_id once rendering begins.

​
Request body

ParameterTypeRequiredDescription
promptstringYesText description of the video you want (1–10,000 characters).
avatar_idstringNoSpecific avatar look ID. Omit to let the agent choose automatically.
voice_idstringNoSpecific voice ID for narration. Omit to let the agent choose automatically.
style_idstringNoStyle ID from GET /v3/video-agents/styles. Applies a curated visual template. See Styles & References.
orientationstringNo"landscape" or "portrait". Auto-detected from content if omitted.
filesarrayNoUp to 20 file attachments. See File input formats below.
callback_urlstringNoWebhook URL to receive a POST notification on completion or failure.
callback_idstringNoCaller-defined ID echoed back in the webhook payload.

​
File input formats

Each item in the files array uses a type discriminator to specify how the file is provided: 
{ "type": "url", "url": "https://example.com/slide-deck.pdf" }
Supported file types: image (png, jpeg), video (mp4, webm), audio (mp3, wav), and pdf. Upload files in advance via 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
  }
}
FieldTypeDescription
session_idstringPrimary identifier for this Video Agent session. Use to track progress.
statusstringSession status: "thinking", "generating", "completed", or "failed".
video_idstring | nullVideo 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_atintegerUnix 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: 
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:
StatusDescription
pendingVideo creation request accepted, queued for processing.
processingThe agent is generating the video.
completedVideo is ready. video_url contains the download link.
failedGeneration failed. Check failure_code and failure_message.

​
Response fields

FieldTypeDescription
idstringUnique video identifier.
titlestring | nullVideo title.
statusstringCurrent status: pending, processing, completed, or failed.
video_urlstring | nullPresigned download URL. Present when completed.
thumbnail_urlstring | nullThumbnail image URL.
gif_urlstring | nullAnimated GIF preview URL.
captioned_video_urlstring | nullVideo with burned-in captions.
subtitle_urlstring | nullSRT subtitle file download URL.
durationnumber | nullVideo duration in seconds.
created_atinteger | nullUnix timestamp of creation.
completed_atinteger | nullUnix timestamp when generation finished.
failure_codestring | nullMachine-readable failure reason. Only when failed.
failure_messagestring | nullHuman-readable failure description. Only when failed.
video_page_urlstring | nullLink 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"
  }'
The 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. Full schema: GET /v3/videos.
ParameterTypeDefaultDescription
limitinteger10Results per page (1–100).
tokenstring—Opaque cursor from a previous response’s next_token.
folder_idstring—Filter by folder ID.
titlestring—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. Full schema: DELETE /v3/videos/{video_id}. 
curl -X DELETE "https://api.heygen.com/v3/videos/vid_xyz789" \
  -H "X-Api-Key: $HEYGEN_API_KEY"
Response
{
  "data": {
    "id": "vid_xyz789",
    "deleted": true
  }
}

​
Tips for better results

  1. 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.
  2. Attach reference files. Pass slides, images, or documents in the files array to give the agent visual context.
  3. Use orientation when you know the target platform (e.g. "portrait" for mobile/social, "landscape" for presentations).
  4. Apply a style for consistent visual branding across videos. See Styles & References and GET /v3/video-agents/styles.
  5. Pin a specific avatar or voice with avatar_id (see Avatars) and voice_id (see Browse Voices) for brand consistency, or omit them to let the agent choose.
  6. Need multi-turn revisions? Use Interactive Sessions instead of one-shot prompts.