![]()
La HeyGen Avatar 6 API può creare un video con presentatore partendo solo da uno script. In modalità avatar pubblico indichi uno dei 1,248 look di stock di HeyGen, invii fino a 1,000 caratteri di text, scegli una delle 102 voci, e heygen-avatar-6 (o heygen-avatar-6-turbo) restituisce un MP4 con lip sync. Nessuna foto, nessuna registrazione, nessun passaggio di sintesi vocale da parte tua. Questa guida spiega come scegliere un look e una voce dal catalogo, dirigere i gesti con prompt, scegliere il formato dell'inquadratura e quanto costa una richiesta di testo. Puoi sfogliare i look anche nella pagina del modello HeyGen Avatar 6.
La richiesta text-to-avatar
Questo è il body documentato per la modalità avatar pubblico con testo:
{
"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"
}
}
| Campo | Obbligatorio | Regola |
|---|---|---|
avatar | Sì | Uno dei 1,248 nomi di look |
text | Sì (al posto di audio_url) | 1–1,000 caratteri |
voice | No | Uno di 102 nomi; predefinito Warm Pro Narrator |
prompt | No | Fino a 1,200 caratteri di regia |
aspect_ratio | No | 16:9 (predefinito), 9:16, 1:1, 4:5, 5:4 |
resolution | No | 1080p (predefinito) o 2K |
È la presenza di avatar a selezionare questa modalità. Non inviare anche image_urls o video_url; usa gli input di una sola modalità per richiesta. Invia a POST https://api.poyo.ai/api/generate/submit e interroga /api/generate/status/{task_id} come nella guida alla HeyGen Avatar 6 API.
Scegli un look di avatar dal catalogo
PoYo pubblica ogni nome nella pagina Avatars and Voices e come catalogo JSON. Il catalogo ha cinque chiavi:
| Chiave | Contenuto |
|---|---|
models | heygen-avatar-6, heygen-avatar-6-turbo (gli stessi nomi funzionano su entrambi) |
default_voice | Warm Pro Narrator |
avatars | Tutti i 1,248 nomi di look, in un elenco piatto |
avatars_by_person | Gli stessi look raggruppati sotto 156 persone |
voices | Tutti i 102 nomi di voce |
Ogni persona ha uno o più look, e ogni look è un valore avatar distinto. Abigail ne ha cinque (Abigail (Upper Body), Abigail Office Front, Abigail Office Side, Abigail Sofa Front, Abigail Sofa Side); Annie ne ha 54; otto persone hanno un solo look. I nomi descrivono ambientazione, abbigliamento e angolo di ripresa, il che di solito basta per scegliere senza anteprima:
| Vuoi | Cerca nomi come | Esempi |
|---|---|---|
| Presentatore rivolto alla camera | Front | Abigail Office Front, Bryan Suit Front |
| Angolo di tre quarti | Side | Abigail Office Side |
| Seduto, informale | Sofa, Sitting, Lounge | Annie Sofa Sitting Front |
| Un ruolo o un'ambientazione | Doctor, Nurse, Yoga, Tech Expert | Ann Doctor Standing, Adriana Nurse Front, Amelia Yoga Front, Bryan Tech Expert |
Circa 480 nomi contengono Front e circa 430 contengono Side. Per una serie di video esplicativi, scegli una persona e resta sui suoi look Front, così il presentatore rimane lo stesso tra un video e l'altro. Usa il look Side corrispondente per gli stacchi.
I nomi corrispondono indipendentemente da maiuscole/minuscole e spazi in eccesso, quindi abigail office front seleziona Abigail Office Front. PoYo controlla avatar rispetto all'elenco all'invio, quindi un refuso restituisce un 400 immediato invece di un task fallito. Valida prima nel tuo codice:
import requests
catalog = requests.get(
"https://docs.poyo.ai/api-manual/video-series/heygen-avatar-6-catalog.json", timeout=30
).json()
def norm(name: str) -> str:
return " ".join(name.split()).lower()
AVATARS = {norm(a): a for a in catalog["avatars"]}
VOICES = set(catalog["voices"])
def build_request(model, avatar, text, voice=None, prompt=None, aspect_ratio="16:9", resolution="1080p"):
if norm(avatar) not in AVATARS:
raise ValueError(f"unknown avatar: {avatar!r}")
if not 1 <= len(text) <= 1000:
raise ValueError("text must be 1-1,000 characters")
if voice is not None and voice not in VOICES:
raise ValueError(f"unknown voice: {voice!r} (copy the exact name from the catalog)")
if prompt is not None and len(prompt) > 1200:
raise ValueError("prompt must be at most 1,200 characters")
body = {"avatar": AVATARS[norm(avatar)], "text": text,
"aspect_ratio": aspect_ratio, "resolution": resolution}
if voice:
body["voice"] = voice
if prompt:
body["prompt"] = prompt
return {"model": model, "input": body}
Il controllo della voce usa di proposito i nomi esatti; la prossima sezione spiega perché.
Scegli una voce
voice decide chi legge text. Se lo ometti ottieni Warm Pro Narrator. Le 102 voci includono nomi semplici (Andrew, Ivy, Jessica Anne Bogart), nomi descrittivi (Calm Chloe, Professor Dean, Radio Rick, Chill Brian) e alcuni con un'indicazione di stile nel nome.
Tre cose mettono in difficoltà:
- Gli spazi finali possono contare. La documentazione segnala che
HopeeHope(con spazio finale) sono due voci diverse. AncheArcher,Cassidy,Adam Stone,Spuds OxleyeAndrew Rizzterminano con uno spazio nel catalogo. Copia i nomi dal JSON invece di riscriverli. - Alcuni nomi contengono emoji o suffissi simili a nomi di file, come
Cute Chloe - Friendly 😊oBrenda - UGC - 1.mp4. Quei caratteri fanno parte del nome. Invia il body della richiesta come JSON UTF-8 e il nome passerà invariato. - La voce non è legata all'avatar. Ognuna delle 102 voci può leggere per ognuno dei 1,248 look. Scegli una voce adatta alla persona sullo schermo; i nostri test del giorno del lancio hanno abbinato
Bryan Tech ExpertadAndreweAbigail Office FrontaJessica Anne Bogart.
voice si applica solo quando invii text. Se invii invece audio_url, l'avatar pronuncia la tua registrazione e voice non viene usato.
Dirigi i gesti con prompt
prompt accetta fino a 1,200 caratteri di regia per gesti, espressione e postura. Il report tecnico di HeyGen descrive la tecnica: "Scrivi l'azione accanto alle parole. Avatar 6 la esegue esattamente al momento giusto." Il suo esempio: "Farmacista cordiale. Su 'Hello', alza il pollice. Su 'the counter on the left', indica il lato con l'indice."
Uno schema che segue quel formato:
{
"model": "heygen-avatar-6",
"input": {
"avatar": "Bryan Tech Expert",
"text": "Hello! Today I will show you three settings that make your dashboard faster. First, open the menu on the left.",
"voice": "Andrew",
"prompt": "Friendly product expert. On 'Hello', wave once. On 'three settings', hold up three fingers. On 'the menu on the left', point to his left side. Keep a relaxed posture and smile between sentences.",
"aspect_ratio": "16:9",
"resolution": "1080p"
}
}
Consigli per prompt utili:
- Cita le parole esatte di
textsu cui deve cadere ogni azione, così il segnale è inequivocabile. - Descrivi prima un ruolo o un tono ("Friendly product expert"), poi i segnali.
- Ometti
promptquando non hai segnali specifici. La pagina di lancio di Avatar 6 di HeyGen dice che il modello "adatta gesti, emozioni ed espressioni al tuo script" da solo.
Scegli le proporzioni in base alla destinazione
aspect_ratio esiste solo in modalità avatar pubblico; le modalità foto e video di riferimento mantengono il formato dell'input.
| Destinazione | aspect_ratio |
|---|---|
| Sito web, YouTube, lezione LMS | 16:9 (predefinito) |
| Shorts, Reels, TikTok, storie | 9:16 |
| Post quadrato nel feed, scheda in-app | 1:1 |
| Post verticale nel feed | 4:5 |
| Post orizzontale nel feed | 5:4 |
resolution è separata: 1080p o 2K con qualsiasi proporzione. Il 2K costa di più al secondo, quindi genera le bozze a 1080p.
Quanto durerà il video e quanto costa
Con il testo, il video dura quanto l'avatar impiega a leggerlo, fino a 1,000 caratteri. Ti viene fatturata la durata del video finito, arrotondata per eccesso al secondo intero. I crediti vengono riservati all'invio e conguagliati sui secondi effettivi quando il task termina.
I nostri test del giorno del lancio sull'API di produzione, 19 novembre 2026 (16:9, 1080p):
| Modello | Avatar / voce | Script | Output | Costo ai prezzi attuali | Tempo reale |
|---|---|---|---|---|---|
heygen-avatar-6-turbo | Abigail Office Front / Jessica Anne Bogart | 27 parole | 10.16 s | 110 crediti ($0.55) | Circa 2.4 min |
heygen-avatar-6 | Bryan Tech Expert / Andrew | 21 parole | 6.88 s | 140 crediti ($0.70) | Circa 2 min |
In queste due esecuzioni fanno circa 2.7 e 3.1 parole al secondo, utile per un budget approssimativo ma non una garanzia, perché il ritmo varia in base a voce e script. Tariffe al secondo: Turbo 10 crediti ($0.05) a 1080p o 18 ($0.09) a 2K; Avatar 6 20 crediti ($0.10) o 29 ($0.145). Vedi Prezzi della HeyGen Avatar 6 API per maggiori dettagli.
Poiché i task di testo mantengono una riserva mentre sono in esecuzione, lanciarne molti insieme può restituire HTTP 200 con code 402 nel body (insufficient_credits_error). Nel nostro test, una terza richiesta è stata rifiutata con: "this request needs at least 252 credits, and 344 credits are already reserved by your unfinished HeyGen Avatar 6 text tasks." Metti in coda i job di testo, oppure mantieni un saldo che copra le riserve in corso. Usa Turbo mentre iteri; il confronto Avatar 6 vs Turbo mostra quando passare all'altro.
Domande frequenti
La HeyGen Avatar 6 API può trasformare un testo in un video con avatar parlante?
Sì. In modalità avatar pubblico, invia avatar, fino a 1,000 caratteri di text e, facoltativamente, voice. Non serve alcun file audio.
Dove si trova l'elenco di avatar e voci della HeyGen Avatar 6 API?
Nella pagina della documentazione PoYo Avatars and Voices, e come catalogo JSON scaricabile con le chiavi avatars, avatars_by_person e voices.
Qual è la voce predefinita della HeyGen Avatar 6 API?
Warm Pro Narrator, usata quando voice è omesso.
Posso usare una mia foto con il testo invece di un avatar di stock?
No. text funziona solo in modalità avatar pubblico. Per una tua foto, usa la modalità foto con image_urls e un audio_url; se serve, genera prima l'audio con un modello TTS.
Quali proporzioni supporta il text to avatar di HeyGen Avatar 6?
16:9, 9:16, 1:1, 4:5 e 5:4, a 1080p o 2K.
Come viene fatturata una richiesta di testo della HeyGen Avatar 6 API?
In base alla durata del video finito, arrotondata per eccesso al secondo intero, alla tariffa al secondo del modello. I crediti vengono riservati all'invio e conguagliati alla fine del task.