Welcoming and calm; opens one hand toward the side on 'القاعة الأولى'.
HeyGen Avatar 6 Avatar to Video API
heygen/avatar-6/identity-to-videoHeyGen Avatar 6 Avatar to Video API turns a script of up to 1,000 characters, or your own audio, into a talking presenter video with one of 1,248 HeyGen stock avatars. Pick one of 102 voices, choose 16:9, 9:16, 1:1, 4:5 or 5:4, and render in 1080p or 2K.
106 / 1000
Examples
REST API
Quick Start
Make your first HeyGen Avatar 6 Avatar 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/identity-to-video",
"input": {
"avatar": "Kavya Outdoor Sport Front",
"text": "Morning run check-in: four kilometers done, my legs are heavy, and my mood is great. Tomorrow we try five.",
"voice": "Juniper",
"aspect_ratio": "16:9",
"prompt": "Holds up four fingers on 'four kilometers', shakes out her legs on 'heavy', gives a thumbs up on 'great'."
}
}'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/identity-to-video",
"input": {
"avatar": "Kavya Outdoor Sport Front",
"text": "Morning run check-in: four kilometers done, my legs are heavy, and my mood is great. Tomorrow we try five.",
"voice": "Juniper",
"aspect_ratio": "16:9",
"prompt": "Holds up four fingers on 'four kilometers', shakes out her legs on 'heavy', gives a thumbs up on 'great'."
}
}
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/identity-to-video. |
| callback_url | string (URL) | No | — | A public HTTP(S) URL for task completion notifications. |
| input | object | Yes | — | Generation parameters. |
| input.avatar | string | Yes | — | Name of one of the 1,248 HeyGen stock avatars, such as Kavya Outdoor Sport Front. Letter case and extra spaces are ignored. |
| input.text | string | No | — | Script for the avatar to read, up to 1,000 characters. |
| input.voice | string | No | Warm Pro Narrator | One of 102 listed voices; other HeyGen voice names are also accepted. |
| input.audio_url | string | No | — | Public HTTP(S) URL of speech audio, 2–60 seconds and up to 15 MB. |
| input.aspect_ratio | string | No | 16:9 | 16:9, 9:16, 1:1, 4:5 or 5:4. |
| 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/identity-to-video | Model ID for asynchronous HeyGen Avatar 6 video generation. |
| Resolution | 1080p / 2K | 1080p by default. |
| Avatars and voices | 1,248 avatars, 102 voices | Text up to 1,000 characters. |
| 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 Avatar to Video API FAQ
What is the HeyGen Avatar 6 Avatar to Video API?
HeyGen Avatar 6 is HeyGen's talking-avatar model, released on November 17, 2026. The HeyGen Avatar 6 Avatar to Video API turns a script of up to 1,000 characters, or your own audio, into a talking presenter video with one of 1,248 HeyGen stock avatars, in 1080p or 2K and five aspect ratios. Choose one of 102 voices for text and cue gestures with a prompt. Call it with the model ID heygen/avatar-6/identity-to-video, or try it in the Playground above.
How much does the HeyGen Avatar 6 Avatar to Video API cost for text scripts?
Avatar 6 costs 20 credits ($0.10) per second at 1080p and 29 credits ($0.145) per second at 2K. For text, ceil(estimated seconds × 1.5) seconds are held at submission; after the video finishes, the charge is its length rounded up, and the difference is refunded.
Which avatars and voices can I use with the model?
1,248 HeyGen stock avatar looks across 156 presenters and 102 listed voices. Search them in the Playground picker or the documentation.
Can the HeyGen Avatar 6 Avatar to Video API use my own voice recording?
Yes. Send audio_url with 2–60 seconds of speech, and the avatar speaks your recording.
Which aspect ratios does the HeyGen Avatar 6 Avatar to Video API support?
16:9 (default), 9:16, 1:1, 4:5 and 5:4, in 1080p or 2K.
How do I call the HeyGen Avatar 6 Avatar to Video API with a script?
POST to https://api.vidgo.ai/api/generate/submit with model heygen/avatar-6/identity-to-video, avatar, text and an optional voice, then poll /api/generate/status/{task_id} or set callback_url.
