how-tos

HeyGen Avatar 6 API-guide: din første snakkende video i cURL og Python

Poyo.ai Team
8 min read
Share:

HeyGen Avatar 6 API-guide: din første snakkende video i cURL og Python

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-key og eksporter den som POYO_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.

FeltModusRegel
modelAlleheygen-avatar-6 eller heygen-avatar-6-turbo
image_urlsFoto (påkrevd), referansevideo (valgfritt)Liste med nøyaktig én URL
video_urlReferansevideoMinst 2 s, opptil 50 MB
avatarOffentlig avatarEtt av de 1,248 oppførte navnene
audio_urlFoto, referansevideo; eller offentlig avatar i stedet for text2–60 s, opptil 15 MB
textOffentlig avatar1–1,000 tegn
voiceOffentlig avatar med textEtt av 102 navn
promptAlleOpptil 1,200 tegn
aspect_ratioOffentlig avatar16:9, 9:16, 1:1, 4:5, 5:4
resolutionAlle1080p (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 svareterror.typeHva du gjør
400validation_error og andreRett inndataene: lyd utenfor 2–60 s, ukjent avatarnavn, et felt fra en annen modus. Ikke prøv igjen uendret
401authentication_errorSjekk Authorization: Bearer-headeren
402insufficient_credits_errorFyll på, eller vent til kjørende tekstoppgaver er gjort opp (se nedenfor)
429rate_limit_errorVent litt og prøv igjen
500 / 502 / 503internal_error, upstream_error, service_errorPrø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):

Modell1080p2K
heygen-avatar-6-turbo10 credits ($0.05) / s18 credits ($0.09) / s
heygen-avatar-620 credits ($0.10) / s29 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.

Share: