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 10% Cashback on Your First Payment (up to $500)

Add funds and get 10% cashback on your first payment (up to $500).

Claim Your Cashback →

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 mode — POST 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
promptYesstring—1–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_idNostring——Style 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 string—up 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_urlYesstring——Publicly accessible URL of the source video to lip-sync (the talking-head clip whose lips are re-synced).
audio_urlYesstring——Publicly accessible URL of the replacement audio file. Its duration should be close to the source video's.
titleNostring——Optional 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
500last 30d
~17 per day
Success rate
100.0%
of completed generations
Generation time
9.7minavg
p95 10.9min
Requests
Sep 17max 300Oct 16
Heygen Video Agent 3.0Avg 17/day
Generation Time
Sep 17max 8.6minOct 16
Heygen Video Agent 3.0Avg 7.7min
Error Rate
Sep 17max 5.0%Oct 16
Heygen Video Agent 3.0Avg 0.0%

〰 Uptime

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

Avg. Success Rate (30d)
100.00%
across all generations of this model family
Uptime
Sep 17max 100%Oct 16
SuccessfulAvg 100.00%