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

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.

Header	Type	Required	Description
Ocp-Apim-Subscription-Key	string	Yes	Your 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.",
  "mode": "generate",
  "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 = {
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
    "prompt": "Cinematic camera move; the subject comes to life, anime style",
    "duration": "5",
    "generate_audio": false,
    "shot_type": "customize"
}

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 = {
  "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
  "prompt": "Cinematic camera move; the subject comes to life, anime style",
  "duration": "5",
  "generate_audio": false,
  "shot_type": "customize"
};

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 '{
    "image_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/Image.jpeg",
    "prompt": "Cinematic camera move; the subject comes to life, anime style",
    "duration": "5",
    "generate_audio": false,
    "shot_type": "customize"
  }'

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"
}

Try Now

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

Header	Required	Default	Description
`X-Webhook-URL`	Yes (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-Mode`	No	`terminal`	`terminal` — 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
`prompt`	Yes	string	—	1-10,000 characters	High-level instruction describing what the video should show. e.g. "A presenter explaining our product launch in 30 seconds".
`mode`	No	string	"generate"	"generate", "chat"	`generate` = fire-and-forget single video; `chat` = multi-turn iterative session.
`avatar_id`	No	string	—	—	Specific HeyGen avatar ID for narration. Omit to let the agent pick.
`voice_id`	No	string	—	—	Specific HeyGen voice ID for text-to-speech. Omit to let the agent pick.
`style_id`	No	string	—	—	Curated visual template ID from HeyGen's style library.
`brand_kit_id`	No	string	—	—	Brand-kit ID applying your colors, fonts, and logos.
`orientation`	No	string	—	"landscape", "portrait"	Video layout. If omitted, the agent auto-detects from the prompt.
`files`	No	array	—	up to 20 items; URL, asset ID, or base64 each	Optional file attachments (images / videos / docs) for the agent to use as reference.
`incognito_mode`	No	boolean	false	true, false	Disables memory injection/extraction for this session.

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.",
  "mode": "generate",
  "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-Type	application/json
Cache-Control	no-cache
Ocp-Apim-Subscription-Key	YOUR_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.

Header	Type	Required	Description
Ocp-Apim-Subscription-Key	string	Yes	Your 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://example.com/input.mp4",
  "audio_url": "https://example.com/voice.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://example.com/input.mp4",
    "audio_url": "https://example.com/voice.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://example.com/input.mp4",
    audio_url: "https://example.com/voice.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://example.com/input.mp4",
    "audio_url": "https://example.com/voice.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"
}

Try Now

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.

Header	Type	Required	Description
X-Webhook-URL	string	No	HTTPS URL to receive the callback. Providing it enables webhook delivery.
X-Webhook-Mode	string	No	`terminal` (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://example.com/input.mp4", "audio_url": "https://example.com/voice.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

Parameter	Required	Type	Default	Allowed values / range	Description
video_url	Yes	string	—	—	Upload the talking-head video clip whose lips will be re-synced to your audio.
audio_url	Yes	string	—	—	The replacement audio. Its duration should be close to the source video's.
title	No	string	—	—	Optional title for the lipsync job.
enable_caption	No	boolean	false	true, false	Generate captions in the output video (a caption file is returned when available).
enable_dynamic_duration	No	boolean	true	true, false	Allow duration adjustment so the video matches the new audio length.
disable_music_track	No	boolean	false	true, false	Remove background music from the source video.
enable_speech_enhancement	No	boolean	false	true, false	Enhance the replacement audio quality.
start_time	No	float	—	—	Start time (seconds) for partial lipsync.
end_time	No	float	—	—	End time (seconds) for partial lipsync.

Content Item Types & Limits

Type	Max	Format / Size	Description
video	1	MP4, MOV · < 32 MB	Source video.
audio	1	MP3, WAV · < 32 MB	Voice / audio track.

Example Request

{
  "video_url": "https://example.com/input.mp4",
  "audio_url": "https://example.com/voice.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

Header	Required	Description
Ocp-Apim-Subscription-Key	Yes	Your API subscription key.
Content-Type	Yes	Must be `application/json`.
X-Webhook-URL	No	HTTPS callback URL (see Webhook section).

Response Handling

Common status codes returned by the submit endpoint.

Status Code	Meaning
202 Accepted	Request queued. Returns `request_id`, `status: "QUEUED"`, and `polling_url`.
400 Bad Request	Invalid request body or unknown model.
401 Unauthorized	Missing or invalid subscription key.
402 Payment Required	Insufficient wallet balance.
403 Forbidden	Subscription not permitted to access this API.
429 Too Many Requests	Rate limit exceeded.
500 Internal Server Error	Unexpected 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

Field	Type	Description
request_id	string	Unique identifier for the request.
status	string	QUEUED, PROCESSING, COMPLETED, FAILED, or ERROR.
model_id	string	The model that handled the request (`heygen-v3-lipsync-precision`).
error	string \| null	Error message when the request fails; null otherwise.
output.media_url	string[]	Array of URLs to the generated lip-synced MP4 video.
output.media_type	string	MIME type of the output (`video/mp4`).
created_at	string	ISO-8601 timestamp when the request was created.
completed_at	string	ISO-8601 timestamp when the request reached a terminal state.
polling_url	string	URL to poll for status (returned on submit).

Status Values & Flow

Status	Meaning
QUEUED	Request accepted and waiting to be processed.
PROCESSING	The lip-sync job is running.
COMPLETED	Done — `output.media_url` contains the synced video.
FAILED / ERROR	Generation 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