Quick science fact: water expands when it freezes, so ice floats, and lakes freeze from the top down.
HeyGen Avatar 6 Turbo Avatar to Video API
heygen/avatar-6-turbo/identity-to-videoHeyGen Avatar 6 Turbo 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.
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 Turbo 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-turbo/identity-to-video",
"input": {
"avatar": "June Sofa Casual Front",
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/identity-to-video/v2/02/input-audio.mp3",
"aspect_ratio": "16:9"
}
}'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-turbo/identity-to-video",
"input": {
"avatar": "June Sofa Casual Front",
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/identity-to-video/v2/02/input-audio.mp3",
"aspect_ratio": "16:9"
}
}
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-turbo/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-turbo/identity-to-video | Model ID for asynchronous HeyGen Avatar 6 Turbo 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 | 10 / 18 credits per second | 1080p / 2K |
Related Models
HeyGen Avatar 6 Turbo Avatar to Video API FAQ
What is the HeyGen Avatar 6 Turbo Avatar to Video API?
HeyGen Avatar 6 Turbo is HeyGen's talking-avatar model, released on November 17, 2026. The HeyGen Avatar 6 Turbo 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-turbo/identity-to-video, or try it in the Playground above.
How much does the HeyGen Avatar 6 Turbo Avatar to Video API cost for text scripts?
Avatar 6 Turbo costs 10 credits ($0.05) per second at 1080p and 18 credits ($0.09) 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 model 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 model 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 Turbo Avatar to Video API with a script?
POST to https://api.vidgo.ai/api/generate/submit with model heygen/avatar-6-turbo/identity-to-video, avatar, text and an optional voice, then poll /api/generate/status/{task_id} or set callback_url.
