Heygen Avatar V API Documentation

Heygen Avatar V API Documentation

Playground

HeyGen Avatar V creates high-quality talking-avatar videos from a selected avatar and speech audio, with optional backgrounds and up to 4K output for presentations, training videos, product introductions, marketing content, and digital human workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

HeyGen Avatar V creates talking-avatar videos from a selected presenter and your own speech recording. Choose an available avatar, upload the audio, and generate the final video at resolutions up to 4K.

Why Choose This?

• Ready-to-use avatars — Choose a presenter from the available avatar selection.
• Audio-driven video — Use your own speech recording to drive the presenter.
• Up to 4K output — Choose 720p, 1080p, or 4k.
• Multiple aspect ratios — Create landscape, portrait, square, and other supported formats.
• Optional background — Add a background image to customize the presentation.

Parameters

How to Use

1. Choose an avatar — Select a presenter from the available options.
2. Upload speech audio — Provide the recording the avatar should speak.
3. Choose output settings — Set the resolution and aspect ratio.
4. Add a background optional — Upload an image for the presentation background.
5. Submit — Generate and retrieve the talking-avatar video.

Pricing

Pricing is based on the input audio duration at $0.15 per billed second.

Audio duration is rounded up to the next whole second, with billing capped at 600 seconds per request.

The same rate applies across all supported resolutions and aspect ratios.

Best Use Cases

• Business presentations — Create presenter-led announcements, updates, and internal communications.
• Training videos — Deliver lessons, onboarding content, and explanations.
• Product introductions — Pair a presenter with prepared product narration.
• Marketing content — Create avatar-led promotional and campaign videos.
• Social content — Produce presenter videos for short-form and branded content.

Pro Tips

• Choose an avatar that matches the tone and purpose of your content.
• Use clear, well-paced speech audio with minimal background noise.
• Select a background that keeps the presenter easy to see.
• Use 720p for lighter workflows and higher resolutions when greater output detail is needed.
• Match the aspect ratio to the platform or placement where the video will be used.

Notes

• avatar and audio are required.
• A presenter must be selected from the available avatar IDs; uploading a portrait instead is not supported.
• Text scripts cannot replace the required speech audio.
• resolution defaults to 1080p.
• aspect_ratio defaults to 16:9.
• Billing is based on the supplied audio duration, not the selected resolution.
• This model is separate from HeyGen Avatar V Digital Twin.

Related Models

• HeyGen Avatar IV — Create talking-avatar videos from a portrait image and speech audio.

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'
{
  "avatar": "Abigail_sitting_sofa_front",
  "audio": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
  "resolution": "1080p",
  "aspect_ratio": "16:9"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/heygen/avatar-v" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

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
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters