how-tos

HeyGen Avatar 6 API-gids: je eerste pratende video in cURL en Python

Poyo.ai Team
9 min read
Share:

HeyGen Avatar 6 API-gids: je eerste pratende video in cURL en Python

Deze HeyGen Avatar 6 API-gids brengt je van een API-sleutel naar een afgewerkte pratende video op PoYo. Je dient één JSON-request in met de model-ID heygen-avatar-6 (of heygen-avatar-6-turbo), bewaart de teruggegeven task-ID en pollt tot de MP4 klaar is. Elke requestbody hieronder volgt de vorm uit de PoYo-docs; de HeyGen Avatar 6-modelpagina heeft een Playground als je de invoer eerst wilt zien.

Voordat je begint

  • Maak een sleutel aan op poyo.ai/dashboard/api-key en exporteer die als POYO_API_KEY. Houd hem op je server.
  • Host elk invoerbestand op een openbare, direct downloadbare HTTP- of HTTPS-URL. PoYo haalt de media zelf op; uploads in de request worden niet geaccepteerd.
  • Kies een tier. Beide ID's accepteren dezelfde velden. Turbo kost 10 credits ($0.05) per seconde in 1080p; Avatar 6 kost 20 credits ($0.10). Zie Avatar 6 vs Turbo.

Je eerste HeyGen Avatar 6 API-request met cURL

De snelste eerste request heeft helemaal geen media nodig: een publieke HeyGen-avatar leest je tekst voor.

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"
    }
  }'

Een geslaagde response bevat "code": 200 en data.task_id, met status op not_started. Dat is een taak in de wachtrij, geen video. Poll hem:

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

De statussen zijn not_started, running, finished en failed. Bij finished staat de MP4 in data.files[] met file_type video, en data.credits_amount toont wat er is afgerekend. Bij failed lees je data.error_message.

Een begrensde polling-loop in Python

In onze tests op de lanceringsdag, 19 november 2026, duurden korte tekstclips ongeveer 2 tot 2.4 minuten van indienen tot resultaat. Deze loop pollt elke 5 seconden (de status-docs raden 2–5 s aan), stopt na 15 minuten en dient bij een time-out nooit opnieuw in, omdat een tweede submit een tweede betaalde taak is.

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)

Voeg in productie een callback_url op het hoogste niveau toe in plaats van te pollen. PoYo post hetzelfde taakobject (zonder de code/data-wrapper) wanneer de taak finished of failed is, ondertekend met HMAC-SHA256 in X-Webhook-Signature; de webhook-docs beschrijven de handtekeningregel.

De drie invoermodi van de HeyGen Avatar 6 API

Er is geen modusschakelaar. avatar kiest de publieke avatarmodus; anders kiest video_url de referentievideomodus; anders draait de request in fotomodus. Gebruik per request de invoer van één modus.

Publieke avatarmodus met tekst

Hierboven getoond. avatar is een van 1,248 publieke looks, text is tot 1,000 tekens, en voice is een van 102 stemmen (standaard Warm Pro Narrator). De text-to-avatar-walkthrough laat zien hoe je looks en stemmen uit de catalogus kiest.

Publieke avatarmodus met je eigen audio

Vervang text en voice door audio_url. aspect_ratio blijft gelden:

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

Fotomodus

Eén foto van een echt persoon plus spraak. De video behoudt de beeldverhouding van de foto, dus snijd de foto bij tot het gewenste kader voordat je hem verstuurt. callback_url staat naast model, niet in 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"
  }
}

Referentievideomodus

Voor geanimeerde of getekende personages. video_url is een clip van het personage; image_urls voegt optioneel één still van hetzelfde personage toe. De output behoudt de beeldverhouding van de clip:

{
  "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"
  }
}

Validatieregels voor velden van de HeyGen Avatar 6 API

Controleer deze in je eigen code voordat je indient; het zijn de gedocumenteerde limieten.

VeldModusRegel
modelAlleheygen-avatar-6 of heygen-avatar-6-turbo
image_urlsFoto (verplicht), referentievideo (optioneel)Array van precies één URL
video_urlReferentievideoMinstens 2 s, tot 50 MB
avatarPublieke avatarEen van de 1,248 vermelde namen
audio_urlFoto, referentievideo; of publieke avatar in plaats van text2–60 s, tot 15 MB
textPublieke avatar1–1,000 tekens
voicePublieke avatar met textEen van 102 namen
promptAlleTot 1,200 tekens
aspect_ratioPublieke avatar16:9, 9:16, 1:1, 4:5, 5:4
resolutionAlle1080p (standaard) of 2K

Avatar- en stemnamen matchen ongeacht hoofdletters en extra spaties, met één gedocumenteerde uitzondering: Hope en Hope (met spatie aan het eind) zijn twee verschillende stemmen. Het invoerschema staat geen extra velden toe, dus stuur geen HeyGen-eigen opties zoals motion_expressiveness of motion_prompt uit de API van HeyGen zelf; op PoYo hoort bewegingsregie in prompt.

Fouten die je moet afhandelen

Lees altijd code in de responsebody. Sommige validatiefouten komen terug als HTTP 200 met "code": 400, dus alleen de HTTP-status controleren is niet genoeg.

Body-codeerror.typeWat te doen
400validation_error en andereCorrigeer de invoer: audio buiten 2–60 s, onbekende avatarnaam, een veld uit een andere modus. Niet ongewijzigd opnieuw proberen
401authentication_errorControleer de Authorization: Bearer-header
402insufficient_credits_errorWaardeer op, of wacht tot lopende teksttaken zijn verrekend (zie hieronder)
429rate_limit_errorWacht even en probeer opnieuw
500 / 502 / 503internal_error, upstream_error, service_errorProbeer opnieuw met exponentiële backoff

Audiolengte, lengte van de referentievideo en de avatarnaam worden bij het indienen gecontroleerd, zodat deze fouten direct als 400 terugkomen in plaats van als een mislukte taak minuten later.

Het geval 402 heeft een HeyGen-specifieke twist. In onze test op de lanceringsdag, nadat twee teksttaken waren ingediend, kwam een derde request (Turbo, 2K, 22 woorden) terug als HTTP 200 met body-code 402 en 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." Teksttaken houden credits vast terwijl ze lopen, dus een reeks tekstsubmits kan een 402 opleveren, ook als de uiteindelijke kosten zouden passen. Zet teksttaken in een wachtrij, of toon de foutmelding aan de gebruiker, omdat die beide getallen al noemt.

Hoe de eerste rekening van de HeyGen Avatar 6 API wordt berekend

PoYo rekent per seconde output af, naar boven afgerond op hele seconden (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
  • Met audio_url (alle modi): de afrekening is de audiolengte, naar boven afgerond, en wordt bij het indienen afgeschreven. Een clip van 12.3 seconden op Avatar 6 in 1080p kost 13 × 20 = 260 credits ($1.30).
  • Met text: credits worden bij het indienen gereserveerd en verrekend met de lengte van de afgewerkte video wanneer de taak eindigt. In onze tests leverde een script van 27 woorden op Turbo 10.16 s op, afgerekend als 11 seconden, wat tegen huidige prijzen 110 credits is (11 s × 10, $0.55); een script van 21 woorden op Avatar 6 leverde 6.88 s op, afgerekend als 7 seconden, wat tegen huidige prijzen 140 credits is (7 s × 20, $0.70).

data.credits_amount op de afgeronde taak is het getal om mee af te stemmen. Meer voorbeelden staan in Prijzen van de HeyGen Avatar 6 API.

Veelgestelde vragen

Hoe roep ik de HeyGen Avatar 6 API aan vanuit Python?

POST JSON naar https://api.poyo.ai/api/generate/submit met requests en poll daarna /api/generate/status/{task_id} met een deadline, zoals in de loop hierboven. Elke HTTP-client werkt; er is geen SDK nodig.

Heeft de HeyGen Avatar 6 API een callback?

Ja. Voeg callback_url toe op het hoogste niveau van de request. PoYo post de taakgegevens wanneer de taak klaar is of mislukt.

Waarom gaf mijn HeyGen Avatar 6 API-request HTTP 200 terug maar geen taak?

Lees de body. Een code anders dan 200 betekent dat de request is mislukt, ook bij HTTP 200; error.message zegt waarom.

Kan ik een bestand rechtstreeks uploaden naar de HeyGen Avatar 6 API?

Nee. image_urls, video_url en audio_url accepteren openbare HTTP- of HTTPS-URL's die PoYo downloadt.

Hoe lang worden resultaten van de HeyGen Avatar 6 API bewaard?

Gegenereerde video's zijn 3 dagen na aanmaak toegankelijk. Download de MP4 naar je eigen opslag.

Share: