![]()
Denne guide til HeyGen Avatar 6 API fører dig fra en API-nøgle til en færdig talende video på PoYo. Du indsender én JSON-request med model-ID'et heygen-avatar-6 (eller heygen-avatar-6-turbo), gemmer det returnerede task-ID og poller, indtil MP4'en er klar. Alle request-bodies nedenfor følger formen i PoYo-dokumentationen; HeyGen Avatar 6-modelsiden har en Playground, hvis du vil se inputtene først.
Før du starter
- Opret en nøgle på
poyo.ai/dashboard/api-key, og eksportér den somPOYO_API_KEY. Hold den på din server. - Host alle inputfiler på en offentlig URL over HTTP eller HTTPS, som kan downloades direkte. PoYo henter selv mediet; upload i selve requesten understøttes ikke.
- Vælg et niveau. Begge ID'er tager de samme felter. Turbo koster 10 credits ($0.05) pr. sekund i 1080p; Avatar 6 koster 20 credits ($0.10). Se Avatar 6 vs Turbo.
Din første HeyGen Avatar 6 API-request med cURL
Den hurtigste første request kræver slet ingen medier: en offentlig HeyGen-avatar læser din tekst op.
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 sat til not_started. Det er et job i kø, ikke en video. Poll det:
curl https://api.poyo.ai/api/generate/status/YOUR_TASK_ID \
-H "Authorization: Bearer $POYO_API_KEY"
Statusserne er not_started, running, finished og failed. Ved finished ligger MP4'en i data.files[] med file_type video, og data.credits_amount viser, hvad der blev opkrævet. Ved failed læser du data.error_message.
En afgrænset polling-løkke i Python
I vores test på lanceringsdagen den 19. november 2026 tog korte tekstklip omkring 2 til 2.4 minutter fra indsendelse til resultat. Denne løkke poller hvert 5. sekund (statusdokumentationen anbefaler 2–5 s), stopper efter 15 minutter og indsender aldrig igen ved timeout, fordi en ny indsendelse er en ny opgave, der faktureres.
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 produktion bør du tilføje en callback_url på øverste niveau i stedet for at polle. PoYo sender det samme task-objekt (uden code / data-indpakningen), når opgaven er finished eller failed, signeret med HMAC-SHA256 i X-Webhook-Signature; webhook-dokumentationen beskriver signaturreglen.
De tre inputtilstande i HeyGen Avatar 6 API
Der er ingen tilstandsvælger. avatar vælger offentlig avatar-tilstand; ellers vælger video_url referencevideo-tilstand; ellers kører requesten i foto-tilstand. Brug input fra én tilstand pr. request.
Offentlig avatar-tilstand med tekst
Vist ovenfor. avatar er et af 1,248 offentlige looks, text er op til 1,000 tegn, og voice er en af 102 stemmer (standard Warm Pro Narrator). Gennemgangen af tekst til avatar viser, hvordan du vælger looks og stemmer fra kataloget.
Offentlig avatar-tilstand med din egen lyd
Udskift text og voice med audio_url. aspect_ratio gælder stadig:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Abigail Sofa Front",
"audio_url": "https://example.com/speech.mp3",
"aspect_ratio": "9:16"
}
}
Foto-tilstand
Ét foto af en rigtig person plus tale. Videoen bevarer fotoets billedformat, så beskær fotoet til den ramme, du vil have, før du sender det. callback_url står ved siden af model, ikke inde 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"
}
}
Referencevideo-tilstand
Til animerede eller tegnede figurer. video_url er et klip af figuren; image_urls kan tilføje ét stillbillede af samme figur. Outputtet bevarer klippets billedformat:
{
"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 felter i HeyGen Avatar 6 API
Kontrollér disse i din egen kode før indsendelse; det er de dokumenterede grænser.
| Felt | Tilstand | Regel |
|---|---|---|
model | Alle | heygen-avatar-6 eller heygen-avatar-6-turbo |
image_urls | Foto (påkrævet), referencevideo (valgfri) | Array med præcis én URL |
video_url | Referencevideo | Mindst 2 s, op til 50 MB |
avatar | Offentlig avatar | Et af de 1,248 navne på listen |
audio_url | Foto, referencevideo; eller offentlig avatar i stedet for text | 2–60 s, op til 15 MB |
text | Offentlig avatar | 1–1,000 tegn |
voice | Offentlig avatar med text | Et af 102 navne |
prompt | Alle | Op til 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 stemmenavne matches uanset store/små bogstaver og ekstra mellemrum, med én dokumenteret undtagelse: Hope og Hope (afsluttende mellemrum) er to forskellige stemmer. Inputskemaet tillader ikke ekstra felter, så send ikke HeyGen-native indstillinger som motion_expressiveness eller motion_prompt fra HeyGens eget API; på PoYo skrives bevægelsesinstruktioner i prompt.
Fejl, der er værd at håndtere
Læs altid code i svarets body. Nogle valideringsfejl kommer tilbage som HTTP 200 med "code": 400, så det er ikke nok kun at tjekke HTTP-statussen.
Body code | error.type | Hvad du gør |
|---|---|---|
| 400 | validation_error og andre | Ret inputtet: lyd uden for 2–60 s, ukendt avatarnavn, et felt fra en anden tilstand. Prøv ikke igen uændret |
| 401 | authentication_error | Tjek headeren Authorization: Bearer |
| 402 | insufficient_credits_error | Fyld op, eller vent på, at kørende tekstopgaver bliver afregnet (se nedenfor) |
| 429 | rate_limit_error | Vent og prøv igen |
| 500 / 502 / 503 | internal_error, upstream_error, service_error | Prøv igen med eksponentiel backoff |
Lydens længde, referencevideoens længde og avatarnavnet kontrolleres ved indsendelse, så disse fejl viser sig som en øjeblikkelig 400 i stedet for en mislykket opgave minutter senere.
402-tilfældet har en HeyGen-specifik drejning. I vores test på lanceringsdagen, efter at to tekstopgaver var indsendt, kom en tredje request (Turbo, 2K, 22 ord) tilbage som HTTP 200 med body-code 402 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." Tekstopgaver holder credits, mens de kører, så en byge af tekstindsendelser kan ramme 402, selv når de endelige beløb ville være dækket. Sæt tekstjob i kø, eller vis fejlmeddelelsen til brugeren, da den allerede angiver begge tal.
Sådan beregnes den første regning for HeyGen Avatar 6 API
PoYo afregner pr. outputsekund, rundet op til hele sekunder (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 |
- Med
audio_url(alle tilstande): beløbet er lydens længde, rundet op, og trækkes ved indsendelse. Et klip på 12.3 sekunder med Avatar 6 i 1080p koster 13 × 20 = 260 credits ($1.30). - Med
text: credits reserveres ved indsendelse og afregnes efter den færdige videos længde, når opgaven slutter. I vores test returnerede et manuskript på 27 ord på Turbo 10.16 s og blev afregnet som 11 sekunder, hvilket er 110 credits (11 s × 10, $0.55) til nuværende priser; et manuskript på 21 ord på Avatar 6 returnerede 6.88 s og blev afregnet som 7 sekunder, hvilket er 140 credits (7 s × 20, $0.70) til nuværende priser.
data.credits_amount på den færdige opgave er tallet, du skal afstemme mod. Flere eksempler finder du i HeyGen Avatar 6 API-priser.
Ofte stillede spørgsmål
Hvordan kalder jeg HeyGen Avatar 6 API fra Python?
Send JSON med POST til https://api.poyo.ai/api/generate/submit med requests, og poll derefter /api/generate/status/{task_id} med en deadline, som i løkken ovenfor. Enhver HTTP-klient virker; der kræves ingen SDK.
Har HeyGen Avatar 6 API et callback?
Ja. Tilføj callback_url på øverste niveau i requesten. PoYo sender opgavens data, når den er færdig eller fejler.
Hvorfor returnerede min HeyGen Avatar 6 API-request HTTP 200, men ingen opgave?
Læs body. En code forskellig fra 200 betyder, at requesten fejlede, også med HTTP 200; error.message fortæller hvorfor.
Kan jeg uploade en fil direkte til HeyGen Avatar 6 API?
Nej. image_urls, video_url og audio_url tager offentlige HTTP- eller HTTPS-URL'er, som PoYo downloader.
Hvor længe gemmes resultater fra HeyGen Avatar 6 API?
Genererede videoer er tilgængelige i 3 dage efter oprettelsen. Download MP4'en til dit eget lager.