Heygen Video Agent 3.0 API - AI Video Generation API: Pricing, Documentation

by HeyGen

Heygen Video Agent 3.0 API is an advanced, prompt-native creative engine designed to automate the entire video production pipeline—including scriptwriting, avatar selection, shot planning, and final editing—from a single text prompt. By functioning as a comprehensive AI production studio, the API autonomously orchestrates the integration of motion graphics, B-roll footage, and voiceovers to deliver broadcast-ready content in minutes. It is built for scalability and enterprise-level automation, allowing developers to convert knowledge bases into multi-scene videos with precise control over visual styles, branding, and multilingual output.

Get API Key
Heygen Video Agent API

Models Version

WELCOME BONUS

Get $5 Free Credit on First Payment

No strings attached — add funds and get $5 bonus instantly

Claim Your $5 →

Heygen Video Agent 3.0 API Documentation

https://gateway.pixazo.ai/heygen-video-agent/v1/heygen-video-agent-request

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour API subscription key

HeyGen Video Agent generate request

Request Code

POST https://gateway.pixazo.ai/heygen-video-agent/v1/heygen-video-agent-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A friendly presenter explaining a new mobile app in 30 seconds, with a cheerful tone and modern background.",
  "orientation": "landscape"
}
import requests

url = "https://gateway.pixazo.ai/heygen-video-agent/v1/heygen-video-agent-request"
headers = {
    "Content-Type": "application/json",
    "Cache-Control": "no-cache",
    "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
}
data = {
    "prompt": "A friendly presenter explaining a new mobile app in 30 seconds, with a cheerful tone and modern background.",
    "orientation": "landscape"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())
const url = "https://gateway.pixazo.ai/heygen-video-agent/v1/heygen-video-agent-request";
const headers = {
  "Content-Type": "application/json",
  "Cache-Control": "no-cache",
  "Ocp-Apim-Subscription-Key": "YOUR_API_KEY"
};
const data = {
  "prompt": "A friendly presenter explaining a new mobile app in 30 seconds, with a cheerful tone and modern background.",
  "orientation": "landscape"
};

fetch(url, {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => console.log(data));
curl -X POST "https://gateway.pixazo.ai/heygen-video-agent/v1/heygen-video-agent-request" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  --data-raw '{
    "prompt": "A friendly presenter explaining a new mobile app in 30 seconds, with a cheerful tone and modern background.",
    "orientation": "landscape"
  }'

Output

{
  "request_id": "heygen-video-agent_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/heygen-video-agent_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Webhook (Optional)

Add the X-Webhook-URL header to your submit request to receive a POST callback when the job completes — no polling required.

Using curl? These are HTTP request headers — pass each with -H, e.g. -H "X-Webhook-URL: https://your-server.com/webhook/callback". Do not paste them as bare lines, and end every line of a multi-line command with \.

Webhook Headers

HeaderRequiredDefaultDescription
X-Webhook-URLYes (to enable)HTTPS endpoint on your server that will receive the POST callback. Must respond 2xx within a few seconds (process async if needed).
X-Webhook-ModeNoterminalterminal — fires once at the final status (COMPLETED/FAILED/ERROR). sync — fires on every poll cycle plus the terminal event, and caps the queue’s polling delay at 15s for tighter progress updates.

Example: enable webhook

X-Webhook-URL: https://your-server.com/webhook/callback
X-Webhook-Mode: terminal

Callback Payload

Your endpoint receives a POST application/json with the same shape as the GET /v2/requests/status/{request_id} response. Example terminal callback (mode terminal):

{
  "request_id": "heygen-video-agent_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "heygen-video-agent",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/heygen-video-agent_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp4"
    ],
    "media_type": "video/mp4"
  },
  "created_at": "2026-05-22T13:17:32.110Z",
  "updated_at": "2026-05-22 13:19:23",
  "completed_at": "2026-05-22 13:19:23"
}

Failure callback shape

{
  "request_id": "heygen-video-agent_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "heygen-video-agent",
  "error": "Description of the error",
  "output": null,
  "created_at": "...",
  "updated_at": "...",
  "completed_at": "..."
}

Delivery semantics

  • terminal mode (default) — exactly one POST when the request reaches a terminal status. No callback during PROCESSING.
  • sync modePOST on every status poll (with delay capped at ~15s) plus a final POST at terminal status. Use when you want progress updates.
  • Idempotency — use request_id as your idempotency key. Network retries can deliver the same callback more than once; your handler must tolerate duplicates.
  • Response — respond 200 OK within a few seconds. The queue does not block on slow handlers, but persistent failures may stop further deliveries.
  • HTTPS required — plain http:// URLs are rejected.

Request Parameters - HeyGen Video Agent generate request

Parameter Required Type Default Allowed values / range Description
promptYesstring1–10,000 charactersNatural-language prompt describing the video to generate. The agent handles avatar selection, scriptwriting, scene composition, and production automatically. e.g. "Create a 30-second product demo video showcasing our new AI features with professional lighting and modern graphics."
avatarNostring"auto""auto" or a HeyGen avatar name (e.g. "Adriana SuitSofa Front") — 1,286 named avatarsAvatar that presents the video. Leave as auto to let the agent pick the avatar that best matches your prompt.
voiceNostring"auto""auto" or a HeyGen voice name (e.g. "Warm Pro Narrator") — 102 named voicesVoice used for the narration. Leave as auto to let the agent pick a voice that suits your prompt.
style_idNostringStyle template ID applying a curated visual look, taken from HeyGen’s v3 video-agent styles library. Omit for the agent’s default styling.
orientationNostring— (auto-detected)"landscape", "portrait"Output video orientation. Auto-detected from the prompt when omitted.
file_urlsNoarray of stringup to 20 URLsPublicly accessible URLs of supporting assets for the agent to use in the video (images, videos, audio, PDFs).
incognito_modeNobooleanfalsetrue, falseWhen true, disables the agent’s memory functions (nothing from this request is remembered or reused).

Example Request

POST https://gateway.pixazo.ai/heygen-video-agent/v1/heygen-video-agent-request
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_API_KEY

{
  "prompt": "A friendly presenter explaining a new mobile app in 30 seconds, with a cheerful tone and modern background.",
  "orientation": "landscape"
}

Response

{
  "request_id": "heygen-video-agent_019xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/heygen-video-agent_019xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Request Headers

Header Value
Content-Typeapplication/json
Cache-Controlno-cache
Ocp-Apim-Subscription-KeyYOUR_SUBSCRIPTION_KEY

Heygen Video Agent 3.0 API Pricing

Your request will cost $0.034 per second of output video.
30-second video ≈ $1.02
2. HeyGen v3 Lipsync Precision

HeyGen v3 Lipsync Precision API Documentation

POST https://gateway.pixazo.ai/heygen-v3-lipsync-precision/v1/video-to-video/lip-sync

Authentication

All requests require an API key passed via header.

HeaderTypeRequiredDescription
Ocp-Apim-Subscription-KeystringYesYour API subscription key

Video + Audio to Video - HeyGen v3 Lipsync Precision

Request Code

POST https://gateway.pixazo.ai/heygen-v3-lipsync-precision/v1/video-to-video/lip-sync
Content-Type: application/json
Cache-Control: no-cache
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/lipsync/talking-head-17s.mp4",
  "audio_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/test-audio/hg_audio17.mp3",
  "enable_dynamic_duration": true
}
import requests

url = "https://gateway.pixazo.ai/heygen-v3-lipsync-precision/v1/video-to-video/lip-sync"
headers = {
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
}
payload = {
    "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/lipsync/talking-head-17s.mp4",
    "audio_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/test-audio/hg_audio17.mp3",
    "enable_dynamic_duration": true
}

resp = requests.post(url, headers=headers, json=payload)
print(resp.json())  # { "request_id": "...", "status": "QUEUED", "polling_url": "..." }
const res = await fetch("https://gateway.pixazo.ai/heygen-v3-lipsync-precision/v1/video-to-video/lip-sync", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Ocp-Apim-Subscription-Key": "YOUR_SUBSCRIPTION_KEY"
  },
  body: JSON.stringify({
    video_url: "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/lipsync/talking-head-17s.mp4",
    audio_url: "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/test-audio/hg_audio17.mp3",
    enable_dynamic_duration: true
  })
});
const data = await res.json();
console.log(data); // { request_id, status: "QUEUED", polling_url }
curl -X POST "https://gateway.pixazo.ai/heygen-v3-lipsync-precision/v1/video-to-video/lip-sync" \
  -H "Content-Type: application/json" \
  -H "Cache-Control: no-cache" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  --data-raw '{
    "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/lipsync/talking-head-17s.mp4",
    "audio_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/test-audio/hg_audio17.mp3",
    "enable_dynamic_duration": true
  }'

Output

{
  "request_id": "heygen-v3-lipsync-precision_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/heygen-v3-lipsync-precision_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Webhook (Optional)

Instead of polling, you can receive a callback when the request reaches a terminal state. Pass the webhook headers on the submit request; the gateway will POST the result to your URL.

HeaderTypeRequiredDescription
X-Webhook-URLstringNoHTTPS URL to receive the callback. Providing it enables webhook delivery.
X-Webhook-ModestringNoterminal (default) fires once on COMPLETED/ERROR; sync fires on each status transition.

Example: enable webhook

curl -X POST "https://gateway.pixazo.ai/heygen-v3-lipsync-precision/v1/video-to-video/lip-sync" \
  -H "Content-Type: application/json" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  -H "X-Webhook-URL: https://your-server.com/webhooks/pixazo" \
  -H "X-Webhook-Mode: terminal" \
  --data-raw '{ "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/lipsync/talking-head-17s.mp4", "audio_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/test-audio/hg_audio17.mp3" }'

Callback Payload (success)

{
  "request_id": "heygen-v3-lipsync-precision_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "heygen-v3-lipsync-precision",
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/heygen-v3-lipsync-precision_019dxxxx.../output.mp4"],
    "media_type": "video/mp4"
  }
}

Failure callback shape

{
  "request_id": "heygen-v3-lipsync-precision_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "error": "Failed to download the file. Please check if the URL is accessible."
}
  • terminal mode delivers one callback on COMPLETED or ERROR; sync mode delivers on each status transition.
  • Deliveries are keyed by request_id — make your handler idempotent.
  • Respond with HTTP 200 within a few seconds; non-2xx responses are retried.
  • The webhook URL must be HTTPS and publicly reachable.

Request Parameters

ParameterRequiredTypeDefaultAllowed values / rangeDescription
video_urlYesstringPublicly accessible URL of the source video to lip-sync (the talking-head clip whose lips are re-synced).
audio_urlYesstringPublicly accessible URL of the replacement audio file. Its duration should be close to the source video's.
titleNostringOptional title for the lipsync job.
enable_captionNobooleanfalsetrue, falseGenerate captions in the output video (a caption file is returned when available).
enable_dynamic_durationNobooleantruetrue, falseAllow duration adjustment so the output matches the new audio length.
disable_music_trackNobooleanfalsetrue, falseRemove the background music track from the source video.
enable_speech_enhancementNobooleanfalsetrue, falseEnhance the replacement audio quality.
start_timeNofloat≥ 0Start time in seconds for a partial lipsync. Use with end_time to re-sync only part of the video.
end_timeNofloat≥ 0End time in seconds for a partial lipsync. Use with start_time to re-sync only part of the video.

Content Item Types & Limits

TypeMaxFormat / SizeDescription
video1MP4, MOV · < 32 MBSource video.
audio1MP3, WAV · < 32 MBVoice / audio track.

Example Request

{
  "video_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/lipsync/talking-head-17s.mp4",
  "audio_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/test-audio/hg_audio17.mp3",
  "enable_dynamic_duration": true
}

Example Response

{
  "request_id": "heygen-v3-lipsync-precision_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "QUEUED",
  "polling_url": "https://gateway.pixazo.ai/v2/requests/status/heygen-v3-lipsync-precision_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

Request Headers

HeaderRequiredDescription
Ocp-Apim-Subscription-KeyYesYour API subscription key.
Content-TypeYesMust be application/json.
X-Webhook-URLNoHTTPS callback URL (see Webhook section).

Response Handling

Common status codes returned by the submit endpoint.

Status CodeMeaning
202 AcceptedRequest queued. Returns request_id, status: "QUEUED", and polling_url.
400 Bad RequestInvalid request body or unknown model.
401 UnauthorizedMissing or invalid subscription key.
402 Payment RequiredInsufficient wallet balance.
403 ForbiddenSubscription not permitted to access this API.
429 Too Many RequestsRate limit exceeded.
500 Internal Server ErrorUnexpected gateway error.

Error Responses

Queue-system errors are returned at submit time; generation errors are surfaced via the status endpoint / webhook with status: "ERROR".

// 402 — insufficient balance
{ "error": "Insufficient balance", "message": "Wallet balance is too low for this request." }

// 400 — model not found / invalid body
{ "error": "Model not found", "message": "Model 'heygen-v3-lipsync-precision' not found or is disabled" }

// generation failure (via status / webhook)
{ "request_id": "heygen-v3-lipsync-precision_019dxxxx...", "status": "ERROR", "error": "Failed to download the input file." }

Retrieving Results

Poll the status endpoint with the request_id until status is COMPLETED (or FAILED/ERROR).

curl -X GET "https://gateway.pixazo.ai/v2/requests/status/heygen-v3-lipsync-precision_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY"

Completed response

{
  "request_id": "heygen-v3-lipsync-precision_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "heygen-v3-lipsync-precision",
  "error": null,
  "output": {
    "media_url": ["https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/heygen-v3-lipsync-precision_019dxxxx.../output.mp4"],
    "media_type": "video/mp4"
  },
  "created_at": "2026-06-30T09:20:33.812Z",
  "completed_at": "2026-06-30T09:22:19.000Z"
}

Response Fields

FieldTypeDescription
request_idstringUnique identifier for the request.
statusstringQUEUED, PROCESSING, COMPLETED, FAILED, or ERROR.
model_idstringThe model that handled the request (heygen-v3-lipsync-precision).
errorstring | nullError message when the request fails; null otherwise.
output.media_urlstring[]Array of URLs to the generated lip-synced MP4 video.
output.media_typestringMIME type of the output (video/mp4).
created_atstringISO-8601 timestamp when the request was created.
completed_atstringISO-8601 timestamp when the request reached a terminal state.
polling_urlstringURL to poll for status (returned on submit).

Status Values & Flow

StatusMeaning
QUEUEDRequest accepted and waiting to be processed.
PROCESSINGThe lip-sync job is running.
COMPLETEDDone — output.media_url contains the synced video.
FAILED / ERRORGeneration failed — see error.

Typical workflow

QUEUED → PROCESSING → COMPLETED (or FAILED / ERROR). Submit the request, then poll GET /v2/requests/status/{request_id} (or use a webhook) until the status is terminal, then download the video from output.media_url.

HeyGen v3 Lipsync Precision API Pricing

Your request will cost $0.10 per second of output video.
17-second clip ≈ $1.70

⚡ Performance

Live usage measured on Pixazo's gateway, split by model version. Generation time is how long a generation takes end-to-end (lower is better). Success rate is the percent of generations that complete (higher is better).

Show data for the last
Generations
3,900last 30d
~130 per day
Success rate
38.5%
of completed generations
Generation time
6.1minavg
p95 6.9min
Requests
Aug 3max 600Sep 1
Heygen Video Agent 3.0Avg 90/day
HeyGen v3 Lipsync PrecisionAvg 40/day
Generation Time
Aug 3max 14.6minSep 1
Heygen Video Agent 3.0Avg 6.4min
HeyGen v3 Lipsync PrecisionAvg 4.5min
Error Rate
Aug 3max 100.0%Sep 1
Heygen Video Agent 3.0Avg 51.9%
HeyGen v3 Lipsync PrecisionAvg 83.3%

〰 Uptime

Percent of generations that succeeded over the selected period, per model version.

Avg. Success Rate (30d)
38.46%
across all generations of this model family
Uptime
Aug 3max 100%Sep 1
Heygen Video Agent 3.0Avg 48.15%
HeyGen v3 Lipsync PrecisionAvg 16.67%