Heygen Avatar Iv API Documentation

Heygen Avatar Iv API Documentation

Playground

HeyGen Avatar IV turns portrait images and speech recordings into expressive talking-avatar videos with expression control, optional backgrounds, and up to 1080P output for digital humans, virtual presenters, personalized content, and avatar video workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

HeyGen Avatar IV turns a portrait image and speech audio into a talking-avatar video. Add optional performance directions, adjust expressiveness, and choose the resolution and background that fit your content.

Why Choose This?

• Photo-to-avatar video — Bring a portrait to life with your own speech audio.
• Performance direction — Guide expressions and movement with an optional prompt.
• Expression control — Choose low, medium, or high expressiveness.
• Flexible presentation — Select resolutions up to 1080p and optionally add a background image.
• Multiple aspect ratios — Create landscape, portrait, square, and other supported layouts.

Parameters

How to Use

1. Upload a portrait — Provide a clear image of the person.
2. Add speech audio — Upload the recording the avatar should speak.
3. Adjust presentation optional — Set performance guidance, expressiveness, background, resolution, or aspect ratio.
4. Submit — Generate and retrieve the talking-avatar video.

Pricing

Pricing is based on the input audio duration at $0.10 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

• Presenter videos — Create spoken introductions, announcements, and presentations.
• Learning content — Turn recorded explanations into avatar-led educational videos.
• Personalized messages — Pair a portrait with custom speech audio.
• Marketing content — Create talking-presenter videos for campaigns and promotions.
• Social content — Produce speech-driven avatar videos for short-form content.

Pro Tips

• Use a sharp portrait with a clearly visible face.
• Use clean speech audio with minimal background noise.
• Keep performance directions clear and specific.
• Choose expressiveness based on the tone of the speech.
• Use a background image when you need more control over the final presentation.

Notes

• image and audio are required.
• resolution defaults to 1080p.
• expressiveness defaults to low.
• Leave aspect_ratio empty to use the closest supported ratio to the portrait.
• The original image dimensions are not preserved automatically.
• Text scripts and avatar IDs cannot replace the required image and audio inputs.
• Billing is based on audio duration, not resolution.

Related Models

• HeyGen Avatar IV — Create talking-avatar videos from a portrait image and speech audio.
• HeyGen Avatar V — Create avatar videos with the newer HeyGen Avatar generation.

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",
  "aspect_ratio": "16:9",
  "expressiveness": "low"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/heygen/avatar-iv" \
  -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