how-tos

Guida alla HeyGen Avatar 6 API: il primo video parlante con cURL e Python

Poyo.ai Team
9 min read
Share:

Guida alla HeyGen Avatar 6 API: il primo video parlante con cURL e Python

Questa guida alla HeyGen Avatar 6 API ti porta da una chiave API a un video parlante finito su PoYo. Invii una richiesta JSON con l'ID modello heygen-avatar-6 (o heygen-avatar-6-turbo), conservi il task ID restituito e fai polling finché l'MP4 non è pronto. Ogni body di richiesta qui sotto segue la struttura della documentazione PoYo; la pagina del modello HeyGen Avatar 6 ha un Playground se vuoi vedere prima gli input.

Prima di iniziare

  • Crea una chiave su poyo.ai/dashboard/api-key ed esportala come POYO_API_KEY. Tienila sul tuo server.
  • Ospita ogni file di input su un URL HTTP o HTTPS pubblico e scaricabile direttamente. PoYo scarica i media da solo; non accetta upload nella richiesta.
  • Scegli un livello. Entrambi gli ID accettano gli stessi campi. Turbo costa 10 crediti ($0.05) al secondo a 1080p; Avatar 6 costa 20 crediti ($0.10). Vedi Avatar 6 vs Turbo.

La tua prima richiesta alla HeyGen Avatar 6 API con cURL

La prima richiesta più rapida non richiede alcun media: un avatar pubblico di HeyGen legge il tuo testo.

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

Una risposta riuscita ha "code": 200 e data.task_id, con status impostato su not_started. È un job in coda, non un video. Fai polling:

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

Gli stati sono not_started, running, finished e failed. Con finished, l'MP4 è in data.files[] con file_type video, e data.credits_amount mostra quanto è stato addebitato. Con failed, leggi data.error_message.

Un loop di polling Python con limite di tempo

Nei nostri test del giorno del lancio, il 19 novembre 2026, le clip brevi da testo hanno impiegato da circa 2 a 2.4 minuti dall'invio al risultato. Questo loop interroga ogni 5 secondi (la documentazione dello stato consiglia 2–5 s), si ferma a 15 minuti e non reinvia mai in caso di timeout, perché un secondo invio è un secondo task fatturabile.

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)

In produzione, aggiungi un callback_url di primo livello invece di fare polling. PoYo invia lo stesso oggetto task (senza il wrapper code / data) quando il task è finished o failed, firmato con HMAC-SHA256 in X-Webhook-Signature; la documentazione dei webhook riporta la regola della firma.

Le tre modalità di input della HeyGen Avatar 6 API

Non c'è un selettore di modalità. avatar seleziona la modalità avatar pubblico; altrimenti video_url seleziona la modalità video di riferimento; altrimenti la richiesta gira in modalità foto. Usa gli input di una sola modalità per richiesta.

Modalità avatar pubblico con testo

Mostrata sopra. avatar è uno dei 1,248 look pubblici, text arriva fino a 1,000 caratteri e voice è una delle 102 voci (predefinita Warm Pro Narrator). La guida text-to-avatar spiega come scegliere look e voci dal catalogo.

Modalità avatar pubblico con il tuo audio

Sostituisci text e voice con audio_url. aspect_ratio resta valido:

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

Modalità foto

Una foto di una persona reale più il parlato. Il video mantiene le proporzioni della foto, quindi ritaglia la foto nell'inquadratura che vuoi prima di inviarla. callback_url sta accanto a model, non dentro 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"
  }
}

Modalità video di riferimento

Per personaggi animati o illustrati. video_url è una clip del personaggio; image_urls aggiunge facoltativamente un fotogramma fisso dello stesso personaggio. L'output mantiene le proporzioni della 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"
  }
}

Regole di validazione dei campi della HeyGen Avatar 6 API

Controllale nel tuo codice prima dell'invio; sono i limiti documentati.

CampoModalitàRegola
modelTutteheygen-avatar-6 o heygen-avatar-6-turbo
image_urlsFoto (obbligatorio), video di riferimento (facoltativo)Array di esattamente un URL
video_urlVideo di riferimentoAlmeno 2 s, fino a 50 MB
avatarAvatar pubblicoUno dei 1,248 nomi in elenco
audio_urlFoto, video di riferimento; oppure avatar pubblico al posto di text2–60 s, fino a 15 MB
textAvatar pubblico1–1,000 caratteri
voiceAvatar pubblico con textUno di 102 nomi
promptTutteFino a 1,200 caratteri
aspect_ratioAvatar pubblico16:9, 9:16, 1:1, 4:5, 5:4
resolutionTutte1080p (predefinito) o 2K

I nomi di avatar e voci corrispondono indipendentemente da maiuscole/minuscole e spazi in eccesso, con un'eccezione documentata: Hope e Hope (con spazio finale) sono due voci diverse. Lo schema di input non ammette campi extra, quindi non inviare opzioni native di HeyGen come motion_expressiveness o motion_prompt dell'API di HeyGen; su PoYo, la regia dei movimenti va in prompt.

Errori da gestire

Leggi sempre code nel body della risposta. Alcuni errori di validazione tornano come HTTP 200 con "code": 400, quindi controllare solo lo stato HTTP non basta.

code nel bodyerror.typeCosa fare
400validation_error e altriCorreggi l'input: audio fuori da 2–60 s, nome avatar sconosciuto, un campo di un'altra modalità. Non ritentare senza modifiche
401authentication_errorControlla l'header Authorization: Bearer
402insufficient_credits_errorRicarica, oppure attendi che i task di testo in corso vengano conguagliati (vedi sotto)
429rate_limit_errorRallenta e ritenta
500 / 502 / 503internal_error, upstream_error, service_errorRitenta con backoff esponenziale

Durata dell'audio, durata del video di riferimento e nome dell'avatar vengono controllati all'invio, quindi questi errori emergono come un 400 immediato invece che come un task fallito minuti dopo.

Il caso 402 ha una particolarità specifica di HeyGen. Nel nostro test del giorno del lancio, dopo l'invio di due task di testo, una terza richiesta (Turbo, 2K, 22 parole) è tornata come HTTP 200 con code 402 nel body e tipo insufficient_credits_error: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." I task di testo trattengono crediti mentre sono in esecuzione, quindi una raffica di invii di testo può ricevere un 402 anche quando gli addebiti finali ci starebbero. Metti in coda i job di testo, oppure mostra il messaggio di errore all'utente, perché riporta già entrambi i numeri.

Come si calcola il primo addebito della HeyGen Avatar 6 API

PoYo fattura per secondo di output, arrotondato per eccesso al secondo intero (1 credito = $0.005):

Modello1080p2K
heygen-avatar-6-turbo10 crediti ($0.05) / s18 crediti ($0.09) / s
heygen-avatar-620 crediti ($0.10) / s29 crediti ($0.145) / s
  • Con audio_url (tutte le modalità): l'addebito è la durata dell'audio, arrotondata per eccesso, e avviene all'invio. Una clip di 12.3 secondi su Avatar 6 a 1080p costa 13 × 20 = 260 crediti ($1.30).
  • Con text: i crediti vengono riservati all'invio e conguagliati sulla durata del video finito quando il task termina. Nei nostri test uno script di 27 parole su Turbo ha prodotto 10.16 s, fatturati come 11 secondi, pari a 110 crediti (11 s × 10, $0.55) ai prezzi attuali; uno script di 21 parole su Avatar 6 ha prodotto 6.88 s, fatturati come 7 secondi, pari a 140 crediti (7 s × 20, $0.70) ai prezzi attuali.

data.credits_amount nel task finito è il numero con cui riconciliare. Altri esempi sono in Prezzi della HeyGen Avatar 6 API.

Domande frequenti

Come chiamo la HeyGen Avatar 6 API da Python?

Invia un POST JSON a https://api.poyo.ai/api/generate/submit con requests, poi fai polling di /api/generate/status/{task_id} con una scadenza, come nel loop qui sopra. Qualsiasi client HTTP va bene; non serve un SDK.

Esiste una callback per la HeyGen Avatar 6 API?

Sì. Aggiungi callback_url al primo livello della richiesta. PoYo invia i dati del task quando termina o fallisce.

Perché la mia richiesta alla HeyGen Avatar 6 API ha restituito HTTP 200 ma nessun task?

Leggi il body. Un code diverso da 200 significa che la richiesta è fallita, anche con HTTP 200; error.message spiega il motivo.

Posso caricare un file direttamente nella HeyGen Avatar 6 API?

No. image_urls, video_url e audio_url accettano URL HTTP o HTTPS pubblici che PoYo scarica.

Per quanto tempo vengono conservati i risultati della HeyGen Avatar 6 API?

I video generati sono accessibili per 3 giorni dalla creazione. Scarica l'MP4 nel tuo storage.

Share: