Heygen Avatar 6 API Documentation
Playground
Try it on WaveSpeedAI!HeyGen Avatar 6 turns a portrait image and speech audio into a talking-avatar video with natural lip sync and prompt-guided, script-aware gestures, making it suitable for digital humans, virtual presenters, marketing content, training, and personalized video workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.
Features
HeyGen Avatar 6 creates a talking-avatar video from a portrait image and speech audio. An optional prompt guides gestures, facial expressions and posture. Choose 1080p or 2k output for presenter clips, product introductions and narrated lessons.
Why Choose This?
- Image and audio input — Use a portrait and a speech recording to create a speaking character.
- Motion guidance — Describe the expression, posture or gestures you would like to see.
- Two output resolutions — Choose
1080por2k; the output follows the image’s aspect ratio. - Audio-driven duration — Process up to 10 minutes of speech per request.
Parameters
| Parameter | Required | Description |
|---|---|---|
image | Yes | Image URL or uploaded portrait of one person. Use a clearly visible face; maximum file size: 32 MB. |
audio | Yes | Audio URL or uploaded speech recording. Up to the first 600 seconds is processed. |
prompt | No | Guidance for gestures, expression and posture. Up to 1,200 characters. Omit this field when no motion guidance is needed. |
resolution | No | 1080p or 2k. Default: 1080p. |
How to Use
- Upload a portrait — Choose an image with one clearly visible person.
- Add speech audio — Upload the recording the character should speak.
- Add motion guidance (optional) — For example: “Face the camera with a relaxed expression and use small hand gestures while speaking.”
- Choose a resolution and submit — Retrieve the generated video when processing finishes.
Pricing
Pricing is based on input audio duration and the selected resolution.
| Resolution | Price |
|---|---|
| 1080p | $0.12/s |
| 2K | $0.17/s |
Audio duration is rounded up to the next whole second, with billing capped at 600 seconds per request. For longer audio, only the first 600 seconds is processed. Adding a prompt does not change the rate.
| Audio Length | Billed Duration | 1080p | 2K |
|---|---|---|---|
| 10s | 10s | $1.20 | $1.70 |
| 10.2s | 11s | $1.32 | $1.87 |
| 60s | 60s | $7.20 | $10.20 |
| 600s | 600s | $72.00 | $102.00 |
Best Use Cases
- Product introductions — Present a product or explain a feature with recorded narration.
- Training and lessons — Create presenter-led clips from prepared speech.
- Announcements — Turn a portrait and a message into a talking video.
- Personalized greetings — Create character-led messages using your own audio.
Pro Tips
- Use a well-lit portrait with an unobstructed face.
- Choose a crop that leaves room for the gestures you request.
- Use clear, single-speaker audio with little background noise.
- Keep motion instructions concise. Complex gestures or precise timing may vary between results.
Notes
- Both
imageandaudioare required. Thepromptguides movement; it does not provide or replace the spoken words. - Only the first 10 minutes of audio is processed. Trim your recording before uploading if you need a different segment.
- Select the image’s crop before uploading; there is no separate aspect-ratio setting.
- Lip-sync, facial detail and gesture accuracy can vary with the source material and requested movement.
- Use images and audio you have permission to use, including the depicted person’s consent where applicable.
Related Models
- HeyGen Avatar 6 Turbo — Explore the lower-priced variant.
Authentication
For authentication details, please refer to the Authentication Guide.
API Endpoints
Submit Task & Query Result
set -euo pipefail
export WAVESPEED_API_KEY="your-api-key"
REQUEST_BODY=$(cat <<'JSON'
{
"image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
"audio": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
"resolution": "1080p"
}
JSON
)
# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--connect-timeout 10 --max-time 60 \
-X POST "https://api.wavespeed.ai/api/v3/heygen/avatar-6" \
-H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
-H "Content-Type: application/json" \
-d "${REQUEST_BODY}"); then
printf 'Submit failed. %s\n' "${CHECK}" >&2
exit 1
fi
TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"
# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
# Transient errors (429, 5xx) are retried, honoring Retry-After.
HTTP_CODE=$(curl --silent --show-error --fail-with-body \
--connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
--output "${BODY_FILE}" --write-out '%{http_code}' \
"${RESULT_URL}" \
-H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
case "${HTTP_CODE}" in
2??) ;;
000|429|5??) # dropped connection or temporary error: keep polling
printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
sleep 10; continue ;;
*) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
cat "${BODY_FILE}" >&2; exit 1 ;;
esac
RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')
case "${STATUS}" in
completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
failed|cancelled|timeout|deleted)
printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
*) sleep 2 ;;
esac
doneRetry temporary errors only while polling, never the submit request. Errors, retries and timeouts
Parameters
Task Submission Parameters
Request Parameters
| Parameter | Type | Required | Default | Range | Description |
|---|---|---|---|---|---|
| image | string | Yes | 1 ~ unlimited characters | A photo or illustration of one person's face (up to 32 MB). The video keeps the image's aspect ratio. | |
| audio | string | Yes | - | 1 ~ unlimited characters | Speech audio that drives the talking video. The video runs as long as the audio. |
| prompt | string | No | 1 ~ 1200 characters | Optional direction for gestures, expression and posture, for example where to point or count on fingers. | |
| resolution | string | No | 1080p | 1080p, 2k | Output video resolution. |
Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.
Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., “success”) |
| data.id | string | Unique identifier for the prediction, Task Id |
| data.model | string | Model ID used for the prediction |
| data.outputs | array | Output values, usually URL strings; some models return text strings or structured result objects (empty when status is not completed) |
| data.urls | object | Object containing related API endpoints |
| data.status | string | Task status. completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses. |
| data.created_at | string | ISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”) |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |
Result Request Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| id | string | Yes | - | Task ID |
Result Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., “success”) |
| data | object | The prediction data object containing all details |
| data.id | string | Unique identifier for the prediction |
| data.model | string | Model ID used for the prediction |
| data.outputs | array<string | object> | Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model. |
| data.urls | object | Object containing related API endpoints |
| data.status | string | Status: completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses |
| data.created_at | string | ISO timestamp of when the request was created |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |