Cheerful and bouncy; on 'ocho canciones' it spreads its arms wide.
HeyGen Avatar 6 Reference Video API
heygen/avatar-6/ref-video-to-videoHeyGen Avatar 6 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 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/ref-video-to-video",
"input": {
"video_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6/ref-video-to-video/v2/01/input-video.mp4",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/heygen/avatar-6/ref-video-to-video/v2/01/input-image.png"
],
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6/ref-video-to-video/v2/01/input-audio.mp3",
"prompt": "He raises one finger to his lips on 'Shh', then points along the shelf on 'poetry'."
}
}'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/ref-video-to-video",
"input": {
"video_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6/ref-video-to-video/v2/01/input-video.mp4",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/heygen/avatar-6/ref-video-to-video/v2/01/input-image.png"
],
"audio_url": "https://cdn.vidgo.ai/apis/models/heygen/avatar-6/ref-video-to-video/v2/01/input-audio.mp3",
"prompt": "He raises one finger to his lips on 'Shh', then points along the shelf on 'poetry'."
}
}
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/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/ref-video-to-video | Model ID for asynchronous HeyGen Avatar 6 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 | 20 / 29 credits per second | 1080p / 2K |
Related Models
HeyGen Avatar 6 Reference Video API FAQ
What is the HeyGen Avatar 6 Reference Video API?
HeyGen Avatar 6 is HeyGen's talking-avatar model, released on November 17, 2026. The HeyGen Avatar 6 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/ref-video-to-video, or try it in the Playground above.
Which characters does the HeyGen Avatar 6 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 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 Reference Video API cost for character videos?
Avatar 6 costs 20 credits ($0.10) per second at 1080p and 29 credits ($0.145) per second at 2K, based on the audio length rounded up. A 5-second line at 1080p costs 100 credits ($0.50).
Should I add image_urls to the HeyGen Avatar 6 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 Reference Video API with a character clip?
POST to https://api.vidgo.ai/api/generate/submit with model heygen/avatar-6/ref-video-to-video, video_url and audio_url, then poll /api/generate/status/{task_id} or set callback_url.
