Heygen Avatar 6 API Documentation

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 1080p or 2k; the output follows the image’s aspect ratio.
  • Audio-driven duration — Process up to 10 minutes of speech per request.

Parameters

ParameterRequiredDescription
imageYesImage URL or uploaded portrait of one person. Use a clearly visible face; maximum file size: 32 MB.
audioYesAudio URL or uploaded speech recording. Up to the first 600 seconds is processed.
promptNoGuidance for gestures, expression and posture. Up to 1,200 characters. Omit this field when no motion guidance is needed.
resolutionNo1080p or 2k. Default: 1080p.

How to Use

  1. Upload a portrait — Choose an image with one clearly visible person.
  2. Add speech audio — Upload the recording the character should speak.
  3. Add motion guidance (optional) — For example: “Face the camera with a relaxed expression and use small hand gestures while speaking.”
  4. Choose a resolution and submit — Retrieve the generated video when processing finishes.

Pricing

Pricing is based on input audio duration and the selected resolution.

ResolutionPrice
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 LengthBilled Duration1080p2K
10s10s$1.20$1.70
10.2s11s$1.32$1.87
60s60s$7.20$10.20
600s600s$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 image and audio are required. The prompt guides 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.

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
done

Retry temporary errors only while polling, never the submit request. Errors, retries and timeouts

Parameters

Task Submission Parameters

Request Parameters

ParameterTypeRequiredDefaultRangeDescription
imagestringYes1 ~ unlimited charactersA photo or illustration of one person's face (up to 32 MB). The video keeps the image's aspect ratio.
audiostringYes-1 ~ unlimited charactersSpeech audio that drives the talking video. The video runs as long as the audio.
promptstringNo1 ~ 1200 charactersOptional direction for gestures, expression and posture, for example where to point or count on fingers.
resolutionstringNo1080p1080p, 2kOutput video resolution.

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

ParameterTypeDescription
codeintegerHTTP status code (e.g., 200 for success)
messagestringStatus message (e.g., “success”)
data.idstringUnique identifier for the prediction, Task Id
data.modelstringModel ID used for the prediction
data.outputsarrayOutput values, usually URL strings; some models return text strings or structured result objects (empty when status is not completed)
data.urlsobjectObject containing related API endpoints
data.statusstringTask status. completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses.
data.created_atstringISO timestamp of when the request was created (e.g., “2023-04-01T12:34:56.789Z”)
data.errorstringError message (empty if no error occurred)
data.timingsobjectObject containing timing details
data.timings.inferenceintegerInference time in milliseconds

Result Request Parameters

ParameterTypeRequiredDefaultDescription
idstringYes-Task ID

Result Response Parameters

ParameterTypeDescription
codeintegerHTTP status code (e.g., 200 for success)
messagestringStatus message (e.g., “success”)
dataobjectThe prediction data object containing all details
data.idstringUnique identifier for the prediction
data.modelstringModel ID used for the prediction
data.outputsarray<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.urlsobjectObject containing related API endpoints
data.statusstringStatus: completed is successful; failed, cancelled, timeout, and deleted are failure terminal statuses
data.created_atstringISO timestamp of when the request was created
data.errorstringError message (empty if no error occurred)
data.timingsobjectObject containing timing details
data.timings.inferenceintegerInference time in milliseconds
© 2026 WaveSpeedAI. All rights reserved.