how-tos

HeyGen Avatar 6 API Guide: First Talking Video in cURL and Python

Poyo.ai Team
8 min read
Share:

HeyGen Avatar 6 API guide: first talking video in cURL and Python

This HeyGen Avatar 6 API guide takes you from an API key to a finished talking video on PoYo. You submit one JSON request with the model ID heygen-avatar-6 (or heygen-avatar-6-turbo), keep the returned task ID, and poll until the MP4 is ready. Every request body below follows the PoYo docs shape; the HeyGen Avatar 6 model page has a Playground if you want to see the inputs first.

Before you start

  • Create a key at poyo.ai/dashboard/api-key and export it as POYO_API_KEY. Keep it on your server.
  • Host every input file at a public, directly downloadable HTTP or HTTPS URL. PoYo fetches the media itself; it does not accept uploads in the request.
  • Pick a tier. Both IDs take the same fields. Turbo costs 10 credits ($0.05) per second at 1080p; Avatar 6 costs 20 credits ($0.10). See Avatar 6 vs Turbo.

Your first HeyGen Avatar 6 API request with cURL

The quickest first request needs no media at all: a HeyGen public avatar reads your text.

curl https://api.poyo.ai/api/generate/submit \
  -H "Authorization: Bearer $POYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-6-turbo",
    "input": {
      "avatar": "Abigail Office Front",
      "text": "Hello and welcome to this demonstration of HeyGen Avatar 6.",
      "voice": "Warm Pro Narrator",
      "prompt": "Speak with calm confidence and nod slightly at the end.",
      "aspect_ratio": "16:9",
      "resolution": "1080p"
    }
  }'

A successful response has "code": 200 and data.task_id, with status set to not_started. That is a queued job, not a video. Poll it:

curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
  -H "Authorization: Bearer $POYO_API_KEY"

Statuses are not_started, running, finished, and failed. When finished, the MP4 is in data.files[] with file_type video, and data.credits_amount shows what was charged. On failed, read data.error_message.

A bounded Python polling loop

In our launch-day tests on November 19, 2026, short text clips took about 2 to 2.4 minutes from submit to result. This loop polls every 5 seconds (the status docs recommend 2–5 s), stops at 15 minutes, and never resubmits on timeout, because a second submit is a second billable task.

import os
import time
import requests

BASE = "https://api.poyo.ai"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["POYO_API_KEY"]


def checked(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        err = body.get("error") or {}
        raise RuntimeError(f"{body.get('code')} {err.get('type')}: {err.get('message')}")
    return body["data"]


def generate(payload, timeout_s=900):
    task = checked(session.post(BASE + "/api/generate/submit", json=payload, timeout=60))
    task_id = task["task_id"]
    print("task", task_id, flush=True)
    deadline = time.monotonic() + timeout_s
    while time.monotonic() < deadline:
        time.sleep(5)
        task = checked(session.get(BASE + "/api/generate/status/" + task_id, timeout=60))
        if task["status"] == "failed":
            raise RuntimeError(task.get("error_message") or "generation failed")
        if task["status"] == "finished":
            videos = [f["file_url"] for f in task.get("files", []) if f.get("file_type") == "video"]
            return videos[0], task.get("credits_amount")
    raise TimeoutError("still running; poll this task again later: " + task_id)


url, credits = generate({
    "model": "heygen-avatar-6",
    "input": {
        "image_urls": ["https://example.com/presenter.png"],
        "audio_url": "https://example.com/speech.mp3",
        "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
        "resolution": "1080p",
    },
})
print(url, credits)

For production, add a top-level callback_url instead of polling. PoYo posts the same task object (without the code / data wrapper) when the task is finished or failed, signed with HMAC-SHA256 in X-Webhook-Signature; the webhook docs give the signature rule.

The three HeyGen Avatar 6 API input modes

There is no mode switch. avatar selects public avatar mode; otherwise video_url selects reference video mode; otherwise the request runs in photo mode. Use one mode's inputs per request.

Public avatar mode with text

Shown above. avatar is one of 1,248 public looks, text is up to 1,000 characters, and voice is one of 102 voices (default Warm Pro Narrator). The text-to-avatar walkthrough covers picking looks and voices from the catalog.

Public avatar mode with your audio

Swap text and voice for audio_url. aspect_ratio still applies:

{
  "model": "heygen-avatar-6",
  "input": {
    "avatar": "Abigail Sofa Front",
    "audio_url": "https://example.com/speech.mp3",
    "aspect_ratio": "9:16"
  }
}

Photo mode

One photo of a real person plus speech. The video keeps the photo's aspect ratio, so crop the photo to the frame you want before sending it. callback_url sits next to model, not inside input:

{
  "model": "heygen-avatar-6",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "image_urls": ["https://example.com/presenter.png"],
    "audio_url": "https://example.com/speech.mp3",
    "prompt": "Face the camera with a warm smile and use small, natural hand gestures.",
    "resolution": "1080p"
  }
}

Reference video mode

For animated or illustrated characters. video_url is a clip of the character; image_urls optionally adds one still of the same character. The output keeps the clip's aspect ratio:

{
  "model": "heygen-avatar-6-turbo",
  "input": {
    "video_url": "https://example.com/cartoon-character.mp4",
    "image_urls": ["https://example.com/cartoon-character.png"],
    "audio_url": "https://example.com/speech.mp3",
    "resolution": "2K"
  }
}

HeyGen Avatar 6 API field validation rules

Check these in your own code before submitting; they are the documented limits.

FieldModeRule
modelAllheygen-avatar-6 or heygen-avatar-6-turbo
image_urlsPhoto (required), reference video (optional)Array of exactly one URL
video_urlReference videoAt least 2 s, up to 50 MB
avatarPublic avatarOne of the 1,248 listed names
audio_urlPhoto, reference video; or public avatar instead of text2–60 s, up to 15 MB
textPublic avatar1–1,000 characters
voicePublic avatar with textOne of 102 names
promptAllUp to 1,200 characters
aspect_ratioPublic avatar16:9, 9:16, 1:1, 4:5, 5:4
resolutionAll1080p (default) or 2K

Avatar and voice names match regardless of letter case and extra spaces, with one documented catch: Hope and Hope (trailing space) are two different voices. The input schema does not allow extra fields, so do not send HeyGen-native options such as motion_expressiveness or motion_prompt from HeyGen's own API; on PoYo, motion direction goes in prompt.

Errors worth handling

Always read code in the response body. Some validation errors come back as HTTP 200 with "code": 400, so checking only the HTTP status is not enough.

Body codeerror.typeWhat to do
400validation_error and othersFix the input: audio outside 2–60 s, unknown avatar name, a field from another mode. Do not retry unchanged
401authentication_errorCheck the Authorization: Bearer header
402insufficient_credits_errorTop up, or wait for running text tasks to settle (below)
429rate_limit_errorBack off and retry
500 / 502 / 503internal_error, upstream_error, service_errorRetry with exponential backoff

Audio length, reference video length, and the avatar name are checked at submission, so these mistakes surface as an immediate 400 rather than a failed task minutes later.

The 402 case has a HeyGen-specific twist. In our launch-day test, after two text tasks were submitted, a third request (Turbo, 2K, 22 words) came back as HTTP 200 with body code 402 and type insufficient_credits_error: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Text tasks hold credits while they run, so a burst of text submissions can hit 402 even when the final charges would fit. Queue text jobs, or show the error message to the user, since it already states both numbers.

How the first HeyGen Avatar 6 API bill is calculated

PoYo bills per output second, rounded up to whole seconds (1 credit = $0.005):

Model1080p2K
heygen-avatar-6-turbo10 credits ($0.05) / s18 credits ($0.09) / s
heygen-avatar-620 credits ($0.10) / s29 credits ($0.145) / s
  • With audio_url (all modes): the charge is the audio length, rounded up, taken at submission. A 12.3-second clip on Avatar 6 at 1080p is 13 × 20 = 260 credits ($1.30).
  • With text: credits are reserved at submission and settled to the finished video's length when the task ends. In our tests a 27-word script on Turbo returned 10.16 s and was billed for 11 seconds, which is 110 credits (11 s × 10, $0.55) at current prices; a 21-word script on Avatar 6 returned 6.88 s and was billed for 7 seconds, which is 140 credits (7 s × 20, $0.70) at current prices.

data.credits_amount on the finished task is the number to reconcile against. More examples are in HeyGen Avatar 6 API pricing.

Frequently asked questions

How do I call the HeyGen Avatar 6 API from Python?

POST JSON to https://api.poyo.ai/api/generate/submit with requests, then poll /api/generate/status/{task_id} with a deadline, as in the loop above. Any HTTP client works; there is no SDK requirement.

Is there a HeyGen Avatar 6 API callback?

Yes. Add callback_url at the top level of the request. PoYo posts the task data when it finishes or fails.

Why did my HeyGen Avatar 6 API request return HTTP 200 but no task?

Read the body. A code other than 200 means the request failed, even with HTTP 200; error.message says why.

Can I upload a file directly to the HeyGen Avatar 6 API?

No. image_urls, video_url, and audio_url take public HTTP or HTTPS URLs that PoYo downloads.

How long are HeyGen Avatar 6 API results kept?

Generated videos are accessible for 3 days after creation. Download the MP4 to your own storage.

Share: