Come si usa l'API di HeyGen Avatar IV? Fai parlare una foto in 5 minuti

TL;DR

• Cos'è: un avatar digitale da foto creato da HeyGen. Una foto ritratto e una battuta (o un audio) generano un MP4 in cui la persona nella foto parla. È già disponibile su HiAPI, apri la pagina del modello e carica una foto per generare.
• Quanto costa: si paga al secondo di video, $0,15 al secondo, 720p e 1080p allo stesso prezzo, 10 secondi costano $1,50.
• Come si chiama l'API: POST https://api.hiapi.ai/v1/tasks, in model scrivi heygen-avatar-iv, passa il link della foto e la battuta, ottieni il taskId e interroga, in 5 minuti fai girare il primo.

Guarda prima un video finito. Questo video orizzontale di 9 secondi qui sotto usa una foto a mezzo busto con un maglione e una battuta in inglese:

1080p / 16:9, 9 secondi, voce Cute Chloe - Friendly. Il maglione, l'acconciatura e la stanza della foto sono conservati, il labiale, gli ammiccamenti e i leggeri cenni del capo seguono la voce.

Testo della battuta:

Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.

Genera con questa battuta → la battuta è già compilata, carica la tua foto e genera.

A chi è adatto HeyGen Avatar IV?

Se hai una foto e vuoi che "questa persona" parli in video, usa questo. Usi comuni:

• Presentazioni di prodotto e promozione: stessa foto, battuta diversa, produci in serie brevi video con punti di forza diversi.
• Corsi e formazione: l'insegnante registra una volta la foto, per ogni lezione scrive solo il copione.
• Comunicazioni aziendali e video per l'assistenza: l'immagine di consulenti, medici e responsabili è fissa, i contenuti si aggiornano in qualsiasi momento.
• Illustrazioni e personaggi 3D: basta un volto chiaro, anche i personaggi dei cartoni animati possono parlare.

Se non vuoi usare la tua immagine, vuoi scegliere tra avatar predefiniti, oppure ti servono sfondo trasparente, sottotitoli o 4K, scegli HeyGen Avatar V, allo stesso prezzo.

Prova prima una volta nella pagina del modello

Prima di scrivere codice, genera un video sul sito per vedere come viene con la tua foto:

1. Clicca su "Genera con questa battuta" qui sopra, la battuta si compila automaticamente.
2. Carica una foto di una sola persona, con il viso frontale e luce uniforme.
3. Scegli 1080p, 16:9, la voce puoi non sceglierla, il predefinito è Warm Pro Narrator.
4. Clicca su genera, quando è pronto guarda l'anteprima online e scarica se sei soddisfatto.

10 secondi costano $1,50, con $10 generi circa 66 secondi di video, abbastanza per confrontare qualche foto e qualche voce.

Tre cose da preparare prima di chiamare l'API

1. API Key: creala nella console, formato sk-..., mettila nell'header Authorization: Bearer.
2. Link HTTPS pubblico della foto: la più affidabile è una foto di una sola persona, viso frontale, lineamenti non coperti, luce uniforme, bocca chiusa naturalmente. L'API legge la foto dal link, prima carica l'immagine sul tuo storage o CDN.
3. Battuta o audio, uno dei due: se dai la battuta la legge la voce scelta; se dai un audio (audio_url) il labiale segue la tua registrazione.

Richiesta minima: versione cURL

Il link della foto qui sotto è utilizzabile direttamente, basta sostituire la tua Key per farlo girare:

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-avatar-iv",
    "input": {
      "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
      "prompt": "Hi, I'\''m Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
      "voice": "Cute Chloe - Friendly",
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    }
  }'

L'ID del task restituito è in data.taskId:

{"code":200,"data":{"taskId":"tk-hiapi-..."},"message":"success"}

La durata non va passata: con la battuta la decide la lunghezza della battuta e la velocità del parlato, con l'audio è lunga quanto l'audio.

Interroga il risultato

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

Dopo che data.status diventa success, cerca in data.output la voce con type uguale a video, il suo url è l'MP4:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-...",
    "status": "success",
    "model": "heygen-avatar-iv",
    "output": [
      {"type": "video", "url": "https://temp.hiapi.ai/.../...-0.mp4"}
    ]
  },
  "message": "success"
}

Esempio Python completo: crea, interroga, scarica

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

payload = {
    "model": "heygen-avatar-iv",
    "input": {
        "image_url": "https://static.hiapi.ai/blog/heygen-avatar-iv/portrait-landscape.jpg",
        "prompt": "Hi, I'm Lin. With one photo and a short script, I can present your product or record a lesson, with natural lip-sync and expressions.",
        "voice": "Cute Chloe - Friendly",
        "resolution": "1080p",
        "aspect_ratio": "16:9",
    },
}

resp = requests.post(API, headers=HEADERS, json=payload, timeout=30)
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

while True:
    data = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(8)

if data["status"] == "success":
    video_url = next(o["url"] for o in data["output"] if o["type"] == "video")
    with open("avatar-iv.mp4", "wb") as f:
        f.write(requests.get(video_url, timeout=120).content)
    print("saved avatar-iv.mp4")
else:
    print(data.get("error"))

Panoramica dei parametri

Parametro	Obbligatorio	Valore predefinito	Descrizione
image_url	Sì	—	Link HTTPS pubblico della foto ritratto, serve un volto chiaro
prompt	Uno dei due	—	Battuta, massimo 5000 caratteri, in cinese o in inglese
voice	No	Warm Pro Narrator	102 voci predefinite, ha effetto solo quando si usa la battuta
audio_url	Uno dei due	—	Audio che guida il labiale, massimo 600 secondi
resolution	No	720p	720p o 1080p, stesso prezzo
aspect_ratio	No	16:9	16:9, 9:16, 4:5, 5:4, 1:1, auto (mantiene le proporzioni della foto)
background	No	Bianco	{"type": "color" o "image", "value": ...}, riempie lo spazio vuoto del formato
callback	No	—	{"url": "...", "when": "final"}, invia l'oggetto del task allo stato finale

L'elenco completo delle voci è nella documentazione in cinese.

I due modi di guida e come usare lo sfondo

Guida con la battuta: passa prompt e voice, adatto per cambiare contenuti in serie. Questo video verticale qui sotto, la foto stessa è 9:16, il formato di uscita riempie esattamente il quadro:

1080p / 9:16, 8 secondi, voce Andrew.

I've been using these new earbuds for a week. The noise canceling is super quiet, and the battery lasts all day. Follow me for more.

Genera con questa battuta → la battuta è già compilata, carica la tua foto verticale e scegli 9:16 per generare.

Guida con l'audio: hai già registrato la voce fuori campo, o vuoi usare la tua voce, sostituisci prompt e voice con audio_url, il labiale e le pause seguono la registrazione.

Sfondo: quando il formato di uscita e le proporzioni della foto sono diversi, il quadro ha dello spazio vuoto, riempilo con background. Per il colore pieno passa {"type": "color", "value": "#F5EFE6"}, per l'immagine passa {"type": "image", "value": "https://..."}. Questo video qui sotto mette una foto orizzontale di un insegnante in verticale, riempiendo sopra e sotto con un'immagine di una lavagna:

1080p / 9:16, 11 secondi, voce Professor Dean, background con un'immagine di una lavagna.

Hello everyone. Today we'll explain the Pythagorean theorem in five minutes. In a right triangle, the squares of the two legs add up to the square of the hypotenuse.

Genera con questa battuta → la battuta è già compilata, carica la tua foto e genera.

3 cose da sapere prima della pubblicazione

1. Sul server usa il callback. Aggiungi alla richiesta "callback": {"url": "https://yourapp.com/webhook", "when": "final"}, il task viene inviato automaticamente alla fine, evitando il polling.
2. Dopo aver ottenuto il taskId non ripetere la POST. Ogni POST /v1/tasks crea un nuovo task e lo fattura separatamente. In caso di timeout di rete controlla prima se hai salvato il taskId, se ce l'hai continua a interrogare o aspetta il callback.
3. Scarica subito dopo il successo. Il link di output scade, appena ottieni il risultato salva l'MP4 sul tuo storage.

Come si fattura?

$0,15 al secondo, si calcola sui secondi effettivi del video generato, la risoluzione non influisce sul prezzo, usa direttamente 1080p. Alla creazione del task si trattiene una stima basata sulla durata, al termine si conguaglia in base ai secondi effettivi, i task falliti vengono rimborsati completamente.

Durata video	Costo
5 secondi	$0,75
10 secondi	$1,50
30 secondi	$4,50
60 secondi	$9,00

Il costo dipende solo dai secondi, per risparmiare scrivi battute brevi. 300 video da 10 secondi al mese costano circa $450, 20 lezioni da 60 secondi circa $180. Il listino completo è nella pagina dei prezzi.

Il video di 9 secondi di Lin all'inizio è costato $1,35. Genera con la stessa battuta → la battuta è già compilata, carica la tua foto e calcola quanti secondi dura il tuo video.

Domande frequenti

Si possono usare battute in cinese? Sì. prompt supporta cinese e inglese, massimo 5000 caratteri.

Posso usare la mia voce? Sì. Passa la registrazione a audio_url, massimo 600 secondi, il labiale segue la tua registrazione.

Che tipo di foto dà i risultati migliori? Una foto di una sola persona, viso frontale, lineamenti non coperti, luce uniforme, bocca chiusa naturalmente. Vanno bene anche illustrazioni e personaggi 3D, purché abbiano un volto chiaro. Per profili laterali, mascherine, foto di gruppo o volti molto piccoli, prova con un'altra foto; i task con riconoscimento fallito vengono rimborsati completamente.

La foto è orizzontale, come faccio un video verticale? Imposta aspect_ratio su 9:16, poi riempi lo spazio sopra e sotto con background, come nel video della lavagna qui sopra.

Quanto tempo serve per un video? La generazione è asincrona, più lunga è la battuta e più alta è la risoluzione, più si aspetta. Sul server usa il callback, che invia automaticamente alla fine.

Link correlati a HeyGen Avatar IV

• Pagina del modello HeyGen Avatar IV: carica una foto e genera online
• Documentazione in cinese di HeyGen Avatar IV: tutti i parametri e le 102 voci
• Pagina del modello HeyGen Avatar V: 497 avatar predefiniti, supporta sfondo trasparente e sottotitoli
• Pagina dei prezzi HiAPI: prezzi al secondo e per immagine di tutti i modelli

Prova subito: trova una tua foto frontale, genera con questa battuta di Lin →, la battuta è già compilata, carica la foto, scegli 1080p, 16:9, un video di circa 9 secondi costa $1,35.