He counts on his fingers on 'dez vezes', shrugs, then grins at the camera.
HeyGen Avatar 6 API
heygen/avatar-6/image-to-videoHeyGen Avatar 6 API turns one photo of a person and 2–60 seconds of speech into a lip-synced talking video in 1080p or 2K. Lips, expression and gestures follow the audio, the video keeps the photo's framing, and an optional prompt cues a gesture on an exact word.
Drag and drop files, paste from clipboard, or provide a URL. Required. One photo of the person (JPEG, PNG or WebP).
1/1 files added
Drag and drop files, paste from clipboard, or provide a URL. Required. 2–60 seconds of speech, up to 15 MB.
1/1 files added
Examples
REST API
Quick Start
Make your first HeyGen Avatar 6 Image to Video request in three steps.
Connect to the Vidgo API
Create an API key, keep it on your server, and send it in the Authorization header as a Bearer token.
- Endpoint
- POST
https://api.vidgo.ai/api/generate/submit - Authentication
- Authorization: Bearer VIDGO_API_KEY
Submit one generation task
Run the example request.
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "heygen/avatar-6/image-to-video",
"input": {
"image_urls": [
"https://cdn.vidgo.ai/apis/models/heygen/avatar-6/image-to-video/v2/01/input-photo.png"
],
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6/image-to-video/v2/01/input-audio.mp3",
"prompt": "He glances out at the sea, then turns back to the camera with a slow smile and a small nod on 'calme'.",
"resolution": "2K"
}
}'Wait for the result
Use the returned task_id until the task reaches finished or failed. On success, read data.files[].file_url.
Track status
GET https://api.vidgo.ai/api/generate/status/{task_id}Poll about every 2 seconds while the status is not_started or running. Stop on finished or failed; on success, read data.files[].file_url. Add callback_url to receive the result asynchronously.
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "TASK_ID",
"status": "not_started",
"created_time": "2026-11-19T08:00:00"
}
}{
"code": 200,
"data": {
"task_id": "TASK_ID",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/.../output.mp4",
"file_type": "video"
}
],
"created_time": "2026-11-19T08:00:00",
"error_message": null,
"progress": 100
}
}Complete runnable example
Submission, polling, terminal-state handling and result extraction in one script.
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "heygen/avatar-6/image-to-video",
"input": {
"image_urls": [
"https://cdn.vidgo.ai/apis/models/heygen/avatar-6/image-to-video/v2/01/input-photo.png"
],
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6/image-to-video/v2/01/input-audio.mp3",
"prompt": "He glances out at the sea, then turns back to the camera with a slow smile and a small nod on 'calme'.",
"resolution": "2K"
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
doneRequest Parameters
model and callback_url belong at the request root; generation parameters belong inside input.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| model | string | Yes | — | Fixed to heygen/avatar-6/image-to-video. |
| callback_url | string (URL) | No | — | A public HTTP(S) URL for task completion notifications. |
| input | object | Yes | — | Generation parameters. |
| input.image_urls | string[] | Yes | — | Exactly one public HTTP(S) URL of a photo of the person to animate. |
| input.audio_url | string | Yes | — | Public HTTP(S) URL of the speech audio, 2–60 seconds and up to 15 MB. The video runs as long as the audio. |
| input.prompt | string | No | — | Direction for gestures, expression and posture, up to 1,200 characters. |
| input.resolution | string | No | 1080p | 1080p or 2K. |
Response Fields
Submission returns the task identity immediately. Status responses add progress, output files or a failure message.
| Field | Type | Description |
|---|---|---|
| code | integer | Application result code. Success uses 0 or 200. |
| message | string | Response or error message when present. |
| data.task_id | string | Task identifier used in the status endpoint. |
| data.status | string | not_started, running, finished or failed. |
| data.created_time | string | Task creation time. |
| data.progress | number | Completion percentage when progress is available. |
| data.files[].file_url | string | Public URL of the generated video. |
| data.files[].file_type | string | File type, here video. |
| data.error_message | string | null | Failure detail when status is failed. |
Task Lifecycle
not_started and running are in progress; finished and failed are terminal, so stop polling on either.
not_startedThe task is accepted and queued.
runningThe video is being generated. Keep polling.
finishedDone. Read the video from data.files[].file_url.
failedGeneration failed. Read data.error_message.
Polling and Errors
- Authentication401 means a missing or invalid Bearer API key; check it in the dashboard.
- Validation400 means invalid parameters; check the fields and durations against the parameter table.
- Polling intervalPoll every 2 seconds and back off to 5 seconds for longer tasks.
- Terminal statesStop polling on finished or failed.
- Callback optionProvide callback_url to receive a notification when the task finishes.
Model Specifications
| Specification | Value | Description |
|---|---|---|
| Model | heygen/avatar-6/image-to-video | Model ID for asynchronous HeyGen Avatar 6 video generation. |
| Resolution | 1080p / 2K | 1080p by default. |
| Audio | 2–60 s, ≤15 MB | With audio, video length follows the audio. |
| Pricing | 20 / 29 credits per second | 1080p / 2K |
Related Models
HeyGen Avatar 6 API FAQ
What is the HeyGen Avatar 6 API for image to video?
HeyGen Avatar 6 is HeyGen's talking-avatar model, released on November 17, 2026. The HeyGen Avatar 6 API for image to video turns one photo of a person and 2–60 seconds of speech into a lip-synced talking video in 1080p or 2K, with expression and gestures that follow the audio. The photo sets the look and framing, and an optional prompt of up to 1,200 characters cues gestures on specific words. Call it with the model ID heygen/avatar-6/image-to-video, or try it in the Playground above.
How much does the HeyGen Avatar 6 API cost?
Avatar 6 costs 20 credits ($0.10) per second at 1080p and 29 credits ($0.145) per second at 2K. Billing uses the audio length rounded up to whole seconds, so a 10-second clip at 1080p costs 200 credits ($1.00).
How long can the audio be for the HeyGen Avatar 6 API?
From 2 to 60 seconds, up to 15 MB. The video runs as long as the audio.
Which photo works best with the HeyGen Avatar 6 API?
A sharp, evenly lit photo of one person with the face and mouth fully visible. The output keeps the photo's aspect ratio.
What can the prompt control in the HeyGen Avatar 6 API?
Gestures, expression and posture. Tie an action to a word, such as a thumbs up on 'great', and the avatar performs it on that word.
How is HeyGen Avatar 6 different from HeyGen Avatar 6 Turbo?
HeyGen Avatar 6 is HeyGen's Quality tier. HeyGen Avatar 6 Turbo takes the same fields on HeyGen's lower-latency stack at half the 1080p price.
How do I call the HeyGen Avatar 6 API?
Send a POST request to https://api.vidgo.ai/api/generate/submit with model heygen/avatar-6/image-to-video, image_urls and audio_url, then poll /api/generate/status/{task_id} or pass a callback_url.
