![]()
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-keyen exporteer die alsPOYO_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.
| Veld | Modus | Regel |
|---|---|---|
model | Alle | heygen-avatar-6 of heygen-avatar-6-turbo |
image_urls | Foto (verplicht), referentievideo (optioneel) | Array van precies één URL |
video_url | Referentievideo | Minstens 2 s, tot 50 MB |
avatar | Publieke avatar | Een van de 1,248 vermelde namen |
audio_url | Foto, referentievideo; of publieke avatar in plaats van text | 2–60 s, tot 15 MB |
text | Publieke avatar | 1–1,000 tekens |
voice | Publieke avatar met text | Een van 102 namen |
prompt | Alle | Tot 1,200 tekens |
aspect_ratio | Publieke avatar | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Alle | 1080p (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-code | error.type | Wat te doen |
|---|---|---|
| 400 | validation_error en andere | Corrigeer de invoer: audio buiten 2–60 s, onbekende avatarnaam, een veld uit een andere modus. Niet ongewijzigd opnieuw proberen |
| 401 | authentication_error | Controleer de Authorization: Bearer-header |
| 402 | insufficient_credits_error | Waardeer op, of wacht tot lopende teksttaken zijn verrekend (zie hieronder) |
| 429 | rate_limit_error | Wacht even en probeer opnieuw |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Probeer 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):
| Model | 1080p | 2K |
|---|---|---|
heygen-avatar-6-turbo | 10 credits ($0.05) / s | 18 credits ($0.09) / s |
heygen-avatar-6 | 20 credits ($0.10) / s | 29 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.