Pixazo API→Models→Heygen Video Agent

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

LIMITED TIME OFFER

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 Text to Video API Documentation

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

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 Text to Video API Pricing

No data available

Could not load current pricing