![]()
Denne guiden til HeyGen Avatar 6 API tar deg fra en API-nøkkel til en ferdig snakkende video på PoYo. Du sender én JSON-forespørsel med modell-ID-en heygen-avatar-6 (eller heygen-avatar-6-turbo), tar vare på oppgave-ID-en du får tilbake, og poller til MP4-en er klar. Alle forespørselsbodyer nedenfor følger formen i PoYo-dokumentasjonen; HeyGen Avatar 6-modellsiden har en Playground hvis du vil se inndataene først.
Før du begynner
- Opprett en nøkkel på
poyo.ai/dashboard/api-keyog eksporter den somPOYO_API_KEY. Hold den på serveren din. - Legg hver inndatafil på en offentlig, direkte nedlastbar HTTP- eller HTTPS-URL. PoYo henter mediene selv; opplastinger i forespørselen godtas ikke.
- Velg et nivå. Begge ID-ene tar de samme feltene. Turbo koster 10 credits ($0.05) per sekund i 1080p; Avatar 6 koster 20 credits ($0.10). Se Avatar 6 vs Turbo.
Din første HeyGen Avatar 6 API-forespørsel med cURL
Den raskeste første forespørselen trenger ingen medier i det hele tatt: en offentlig HeyGen-avatar leser opp teksten din.
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"
}
}'
Et vellykket svar har "code": 200 og data.task_id, med status satt til not_started. Det er en jobb i kø, ikke en video. Poll den:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Statusene er not_started, running, finished og failed. Ved finished ligger MP4-en i data.files[] med file_type video, og data.credits_amount viser hva som ble belastet. Ved failed leser du data.error_message.
En avgrenset polling-løkke i Python
I testene våre på lanseringsdagen 19. november 2026 tok korte tekstklipp omtrent 2 til 2.4 minutter fra innsending til resultat. Denne løkken poller hvert 5. sekund (statusdokumentasjonen anbefaler 2–5 s), stopper etter 15 minutter og sender aldri inn på nytt ved tidsavbrudd, fordi en ny innsending er en ny fakturerbar oppgave.
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)
I produksjon bør du legge til en callback_url på toppnivå i stedet for å polle. PoYo poster det samme oppgaveobjektet (uten code/data-innpakningen) når oppgaven er finished eller failed, signert med HMAC-SHA256 i X-Webhook-Signature; webhook-dokumentasjonen gir signaturregelen.
De tre inndatamodusene i HeyGen Avatar 6 API
Det finnes ingen modusbryter. avatar velger offentlig avatar-modus; ellers velger video_url referansevideomodus; ellers kjører forespørselen i fotomodus. Bruk inndataene for én modus per forespørsel.
Offentlig avatar-modus med tekst
Vist ovenfor. avatar er én av 1,248 offentlige looks, text er opptil 1,000 tegn, og voice er én av 102 stemmer (standard Warm Pro Narrator). Text-to-avatar-gjennomgangen viser hvordan du velger looks og stemmer fra katalogen.
Offentlig avatar-modus med din egen lyd
Bytt ut text og voice med audio_url. aspect_ratio gjelder fortsatt:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Fotomodus
Ett foto av en ekte person pluss tale. Videoen beholder fotoets sideforhold, så beskjær fotoet til ønsket utsnitt før du sender det. callback_url står ved siden av model, ikke inne i 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"
}
}
Referansevideomodus
For animerte eller illustrerte figurer. video_url er et klipp av figuren; image_urls legger valgfritt til ett stillbilde av den samme figuren. Outputen beholder klippets sideforhold:
{
"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"
}
}
Valideringsregler for feltene i HeyGen Avatar 6 API
Sjekk disse i din egen kode før du sender inn; dette er de dokumenterte grensene.
| Felt | Modus | Regel |
|---|---|---|
model | Alle | heygen-avatar-6 eller heygen-avatar-6-turbo |
image_urls | Foto (påkrevd), referansevideo (valgfritt) | Liste med nøyaktig én URL |
video_url | Referansevideo | Minst 2 s, opptil 50 MB |
avatar | Offentlig avatar | Ett av de 1,248 oppførte navnene |
audio_url | Foto, referansevideo; eller offentlig avatar i stedet for text | 2–60 s, opptil 15 MB |
text | Offentlig avatar | 1–1,000 tegn |
voice | Offentlig avatar med text | Ett av 102 navn |
prompt | Alle | Opptil 1,200 tegn |
aspect_ratio | Offentlig avatar | 16:9, 9:16, 1:1, 4:5, 5:4 |
resolution | Alle | 1080p (standard) eller 2K |
Avatar- og stemmenavn matches uavhengig av store/små bokstaver og ekstra mellomrom, med ett dokumentert unntak: Hope og Hope (med mellomrom på slutten) er to forskjellige stemmer. Inndataskjemaet tillater ikke ekstra felt, så ikke send HeyGen-spesifikke valg som motion_expressiveness eller motion_prompt fra HeyGens eget API; på PoYo legges bevegelsesinstrukser i prompt.
Feil som er verdt å håndtere
Les alltid code i svaret. Noen valideringsfeil kommer tilbake som HTTP 200 med "code": 400, så det er ikke nok å bare sjekke HTTP-statusen.
code i svaret | error.type | Hva du gjør |
|---|---|---|
| 400 | validation_error og andre | Rett inndataene: lyd utenfor 2–60 s, ukjent avatarnavn, et felt fra en annen modus. Ikke prøv igjen uendret |
| 401 | authentication_error | Sjekk Authorization: Bearer-headeren |
| 402 | insufficient_credits_error | Fyll på, eller vent til kjørende tekstoppgaver er gjort opp (se nedenfor) |
| 429 | rate_limit_error | Vent litt og prøv igjen |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Prøv igjen med eksponentiell backoff |
Lydlengde, lengden på referansevideoen og avatarnavnet sjekkes ved innsending, så disse feilene dukker opp som en umiddelbar 400 i stedet for en mislykket oppgave minutter senere.
402-tilfellet har en HeyGen-spesifikk vri. I testen vår på lanseringsdagen, etter at to tekstoppgaver var sendt inn, kom en tredje forespørsel (Turbo, 2K, 22 ord) tilbake som HTTP 200 med code 402 i svaret og typen insufficient_credits_error: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Tekstoppgaver holder av credits mens de kjører, så en rekke tekstinnsendinger kan treffe 402 selv når de endelige kostnadene ville fått plass. Legg tekstjobber i kø, eller vis feilmeldingen til brukeren, siden den allerede oppgir begge tallene.
Slik beregnes den første regningen for HeyGen Avatar 6 API
PoYo fakturerer per sekund output, rundet opp til hele sekunder (1 credit = $0.005):
| Modell | 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 |
- Med
audio_url(alle moduser): belastningen er lydlengden, rundet opp, og trekkes ved innsending. Et klipp på 12.3 sekunder på Avatar 6 i 1080p blir 13 × 20 = 260 credits ($1.30). - Med
text: credits reserveres ved innsending og gjøres opp mot lengden på den ferdige videoen når oppgaven avsluttes. I testene våre ga et manus på 27 ord på Turbo 10.16 s og ble fakturert som 11 sekunder, som er 110 credits (11 s × 10, $0.55) med dagens priser; et manus på 21 ord på Avatar 6 ga 6.88 s og ble fakturert som 7 sekunder, som er 140 credits (7 s × 20, $0.70) med dagens priser.
data.credits_amount på den ferdige oppgaven er tallet du skal avstemme mot. Flere eksempler finner du i Priser for HeyGen Avatar 6 API.
Ofte stilte spørsmål
Hvordan kaller jeg HeyGen Avatar 6 API fra Python?
POST JSON til https://api.poyo.ai/api/generate/submit med requests, og poll deretter /api/generate/status/{task_id} med en tidsfrist, som i løkken ovenfor. Alle HTTP-klienter fungerer; det kreves ingen SDK.
Har HeyGen Avatar 6 API callback?
Ja. Legg til callback_url på toppnivå i forespørselen. PoYo poster oppgavedataene når den er ferdig eller feiler.
Hvorfor returnerte HeyGen Avatar 6 API-forespørselen min HTTP 200, men ingen oppgave?
Les svaret. En code som ikke er 200 betyr at forespørselen feilet, selv med HTTP 200; error.message forteller hvorfor.
Kan jeg laste opp en fil direkte til HeyGen Avatar 6 API?
Nei. image_urls, video_url og audio_url tar offentlige HTTP- eller HTTPS-URL-er som PoYo laster ned.
Hvor lenge oppbevares resultater fra HeyGen Avatar 6 API?
Genererte videoer er tilgjengelige i 3 dager etter at de ble opprettet. Last ned MP4-en til din egen lagring.