Points at the map with its flipper on 'kalt und klar'.
HeyGen Avatar 6 Turbo Reference Video API
heygen/avatar-6-turbo/ref-video-to-videoHeyGen Avatar 6 Turbo Reference Video API gives animated and illustrated characters a voice: send a short video of the character and 2–60 seconds of speech, and get a lip-synced talking video in 1080p or 2K that keeps the character's art style and the clip's framing.
Drag and drop files, paste from clipboard, or provide a URL. Required. Animated or illustrated character clip, 2 seconds or longer, up to 50 MB.
1/1 files added
Drag and drop files, paste from clipboard, or provide a URL. Optional. One still image of the same character.
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 Turbo Reference Video 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/ref-video-to-video",
"input": {
"video_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-video.mp4",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-image.png"
],
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-audio.mp3",
"prompt": "He lifts the parcel on 'Parcel' and winks on 'I promise'."
}
}'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/ref-video-to-video",
"input": {
"video_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-video.mp4",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-image.png"
],
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6-turbo/ref-video-to-video/v2/01/input-audio.mp3",
"prompt": "He lifts the parcel on 'Parcel' and winks on 'I promise'."
}
}
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/ref-video-to-video. |
| callback_url | string (URL) | No | — | A public HTTP(S) URL for task completion notifications. |
| input | object | Yes | — | Generation parameters. |
| input.video_url | string | Yes | — | Public HTTP(S) URL of a video of an animated or illustrated character, at least 2 seconds and up to 50 MB. |
| input.image_urls | string[] | No | — | One public HTTP(S) URL of a still image of the same character. |
| input.audio_url | string | Yes | — | Public HTTP(S) URL of the speech audio, 2–60 seconds and up to 15 MB. |
| 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/ref-video-to-video | Model ID for asynchronous HeyGen Avatar 6 Turbo video generation. |
| Resolution | 1080p / 2K | 1080p by default. |
| Reference video | ≥2 s, ≤50 MB | Animated or illustrated character. |
| 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 Reference Video API FAQ
What is the HeyGen Avatar 6 Turbo Reference Video API?
HeyGen Avatar 6 Turbo is HeyGen's talking-avatar model, released on November 17, 2026. The HeyGen Avatar 6 Turbo Reference Video API turns a short clip of a cartoon or illustrated character and 2–60 seconds of speech into a lip-synced talking video in 1080p or 2K, keeping the character's art style. An optional still of the same character and a prompt of up to 1,200 characters refine the result. Call it with the model ID heygen/avatar-6-turbo/ref-video-to-video, or try it in the Playground above.
Which characters does the HeyGen Avatar 6 Turbo Reference Video API support in this mode?
Animated and illustrated characters: claymation, 2D cartoons, watercolor, low-poly 3D, paper craft and similar styles.
How long should the reference video be for the HeyGen Avatar 6 Turbo Reference Video API?
At least 2 seconds, up to 50 MB. The output keeps the clip's aspect ratio.
How much does the HeyGen Avatar 6 Turbo Reference Video API cost for character videos?
Avatar 6 Turbo costs 10 credits ($0.05) per second at 1080p and 18 credits ($0.09) per second at 2K, based on the audio length rounded up. A 5-second line at 1080p costs 50 credits ($0.25).
Should I add image_urls to the HeyGen Avatar 6 Turbo Reference Video API request?
Add one still of the same character when the clip shows the face small or at an angle; it gives the model a clear reference.
How do I call the HeyGen Avatar 6 Turbo Reference Video API with a character clip?
POST to https://api.vidgo.ai/api/generate/submit with model heygen/avatar-6-turbo/ref-video-to-video, video_url and audio_url, then poll /api/generate/status/{task_id} or set callback_url.
