how-tos

HeyGen Avatar 6 API text to avatar: video con presentatore da uno script, senza file audio

Poyo.ai Team
9 min read
Share:

HeyGen Avatar 6 API text to avatar: un video con presentatore da uno script

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"
  }
}
CampoObbligatorioRegola
avatarSìUno dei 1,248 nomi di look
textSì (al posto di audio_url)1–1,000 caratteri
voiceNoUno di 102 nomi; predefinito Warm Pro Narrator
promptNoFino a 1,200 caratteri di regia
aspect_ratioNo16:9 (predefinito), 9:16, 1:1, 4:5, 5:4
resolutionNo1080p (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.

PoYo pubblica ogni nome nella pagina Avatars and Voices e come catalogo JSON. Il catalogo ha cinque chiavi:

ChiaveContenuto
modelsheygen-avatar-6, heygen-avatar-6-turbo (gli stessi nomi funzionano su entrambi)
default_voiceWarm Pro Narrator
avatarsTutti i 1,248 nomi di look, in un elenco piatto
avatars_by_personGli stessi look raggruppati sotto 156 persone
voicesTutti 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:

VuoiCerca nomi comeEsempi
Presentatore rivolto alla cameraFrontAbigail Office Front, Bryan Suit Front
Angolo di tre quartiSideAbigail Office Side
Seduto, informaleSofa, Sitting, LoungeAnnie Sofa Sitting Front
Un ruolo o un'ambientazioneDoctor, Nurse, Yoga, Tech ExpertAnn 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 Hope e Hope (con spazio finale) sono due voci diverse. Anche Archer , Cassidy , Adam Stone , Spuds Oxley e Andrew Rizz terminano 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 😊 o Brenda - 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 Expert ad Andrew e Abigail Office Front a Jessica 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 text su cui deve cadere ogni azione, così il segnale è inequivocabile.
  • Descrivi prima un ruolo o un tono ("Friendly product expert"), poi i segnali.
  • Ometti prompt quando 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.

Destinazioneaspect_ratio
Sito web, YouTube, lezione LMS16:9 (predefinito)
Shorts, Reels, TikTok, storie9:16
Post quadrato nel feed, scheda in-app1:1
Post verticale nel feed4:5
Post orizzontale nel feed5: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):

ModelloAvatar / voceScriptOutputCosto ai prezzi attualiTempo reale
heygen-avatar-6-turboAbigail Office Front / Jessica Anne Bogart27 parole10.16 s110 crediti ($0.55)Circa 2.4 min
heygen-avatar-6Bryan Tech Expert / Andrew21 parole6.88 s140 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.

Share: