Trasformare una sceneggiatura in un breve video parlato con heygen-avatar-v e l'API di hiapi

I contenuti parlati per i brevi video — aggiornamenti del fondatore, demo di prodotto, spot in stile UGC — di solito significano prenotare una persona reale, preparare un microfono e fare un altro giro di montaggio. heygen-avatar-v su hiapi riduce tutto questo a una singola chiamata API: invii una sceneggiatura o un file audio e ricevi indietro un video con avatar sincronizzato labiale, con movimenti naturali di inattività e una traccia di sottotitoli, pronto per il feed dei brevi video. Questo articolo percorre il flusso di lavoro reale di /v1/tasks, una clip video realmente generata, i vincoli da conoscere prima di costruirci una pipeline intorno e i prezzi recuperati in tempo reale da /api/pricing di hiapi. Se cerchi consigli di stile a livello di prompt per l'avatar stesso, heygen-avatar-v prompt recipes li copre già — questo articolo riguarda invece come collegare il modello a una pipeline riutilizzabile per brevi video.

Cosa produce effettivamente heygen-avatar-v

heygen-avatar-v è un modello di video con persona digitale, non un generatore di testo in video nel senso di Sora/Kling — utilizza una sceneggiatura testuale o un file audio caricato per guidare un avatar HeyGen predefinito e restituisce un video in cui la bocca dell'avatar è sincronizzata con il parlato e presenta sottili movimenti continui (sbattimenti di palpebre, leggeri spostamenti della testa, oscillazioni delle spalle), così non sembra un ritratto statico. Questo comportamento di "movimento anche quando è inattivo" è esattamente la linea di demarcazione tra una clip breve utilizzabile e una foto parlante che si riconosce subito come finta.

Il modello è guidato da due tipi di input, mutuamente esclusivi — ne invii uno oppure l'altro:

• prompt — la sceneggiatura testuale; viene letta dal TTS di hiapi e guida la sincronizzazione labiale
• audio_url — un URL pubblico che punta a una traccia vocale preregistrata (la tua voce, una voce clonata, quello che vuoi), che guida la sincronizzazione labiale

Non c'è un campo duration. La lunghezza della clip dipende interamente da quanto dura la riproduzione della sceneggiatura o dell'audio — una battuta di 40 parole produrrà una clip più breve di una di 200 parole. Questo è importante per la pianificazione dei costi, come vedremo più avanti.

Campi opzionali per rifinire lo stile: avatar (scelto dalla libreria di preset HeyGen), voice (usato solo insieme a prompt, ignorato con audio_url), aspect_ratio (9:16 per Reels/TikTok/Shorts, 16:9, 1:1), resolution, background (tinta unita o scena — ma vedi la trappola qui sotto), caption (genera una traccia di sottotitoli) e output_format (mp4 o webm, quest'ultimo con sfondo trasparente per la composizione sulle proprie scene).

Clip reale: sceneggiatura in input, video con avatar e sottotitoli in output

Qui sotto c'è un output reale di heygen-avatar-v — l'avatar pronuncia una battuta di sceneggiatura, con movimenti di inattività visibili tra le frasi e una traccia di sottotitoli sincronizzata:

Nota cosa non succede: l'avatar non si blocca tra le frasi e i sottotitoli seguono il parlato invece di essere applicati a posteriori. Questa combinazione — movimento continuo più sottotitoli temporizzati — è l'intera ragione per scegliere questo modello invece di doppiare un'immagine statica dell'avatar in un editor.

Le trappole: due problemi che morderanno la prima versione della pipeline

caption restituisce un file di sottotitoli allegato, non sottotitoli impressi nel video. Impostare caption: true restituisce un file .srt sincronizzato in aggiunta al video in output — non incide il testo nei fotogrammi del video. Se vuoi che il testo dei sottotitoli appaia sullo schermo (l'aspetto tipico della maggior parte delle piattaforme di brevi video), devi fare un passaggio separato di masterizzazione usando quel file .srt (ffmpeg -i clip.mp4 -vf subtitles=captions.srt output.mp4, oppure la funzione nativa di importazione sottotitoli della tua piattaforma). Tratta i "sottotitoli" dell'API come dati, non come immagine renderizzata.

background funziona solo con avatar in stile illustrazione, non con quelli in stile fotorealistico. La libreria di avatar HeyGen mescola avatar fotorealistici e avatar in stile illustrazione/animazione. Il parametro background riesce a sostituire la scena dietro un avatar in stile illustrazione, ma gli avatar fotorealistici mantengono lo sfondo originale della registrazione indipendentemente da cosa passi — il modello non lo ritaglia. Se la tua pipeline presume che ogni avatar accetti una sovrascrittura dello sfondo, testa prima lo specifico avatar ID che intendi usare, prima di dare per scontato che verrà composto come ti aspetti. Per gli avatar fotorealistici che vuoi posizionare sul tuo sfondo, l'approccio affidabile è output_format: webm (trasparente).

Costi: fatturazione per secondi di output, non per numero di chiamate

Secondo il /api/pricing in tempo reale di hiapi, heygen-avatar-v costa $0,15 per secondo di output — tariffa uniforme indipendentemente da risoluzione o aspect ratio. Poiché non c'è un input di durata, il costo effettivo dipende da quanto dura la riproduzione della sceneggiatura o dell'audio:

Lunghezza sceneggiatura (approx.)	Durata output	Costo
Battuta gancio breve	Circa 5 secondi	$0,75
Un beat di breve video	Circa 10 secondi	$1,50
Pitch su più frasi	Circa 20 secondi	$3,00
Spot parlato completo da 30 secondi	Circa 30 secondi	$4,50

Poiché il costo scala con la lunghezza del parlato e non con un parametro impostato in anticipo, la pratica utile è cronometrare la sceneggiatura prima di inviare il task (leggendola ad alta voce, oppure facendola passare da uno stimatore di lunghezza TTS), invece di scoprire la fattura solo dopo aver renderizzato la clip.

La pipeline: invia, fai polling, scarica prima della scadenza

heygen-avatar-v gira sull'endpoint asincrono /v1/tasks di hiapi — come ogni altro modello basato su task della piattaforma, è la forma "crea prima, poi fai polling". Un dettaglio specifico di questo flusso di lavoro: i task passano attraverso una fase di archiving tra handling e success, durante la quale la piattaforma sta completando il video e i file allegati dei sottotitoli, quindi non trattare archiving come stato terminale nel tuo ciclo di polling.

import time
import requests

API_KEY = "sk-your-hiapi-key"  # from https://www.hiapi.ai/en/dashboard/api-keys
BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}

def create_avatar_video(script: str, avatar: str, aspect_ratio: str = "9:16") -> str:
    payload = {
        "model": "heygen-avatar-v",
        "input": {
            "prompt": script,
            "avatar": avatar,
            "aspect_ratio": aspect_ratio,
            "caption": True,
        },
    }
    resp = requests.post(BASE, headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()["data"]["taskId"]

def wait_for_video(task_id: str, timeout_s: int = 300, poll_every: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        task = resp.json()["data"]
        status = task["status"]
        if status == "success":
            return task["output"]  # [{"url": "...mp4"}, {"url": "...srt"}] — download both, now
        if status == "failed":
            err = task.get("error", {})
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        # "handling" and "archiving" are both non-terminal — keep polling
        time.sleep(poll_every)
    raise TimeoutError(f"task {task_id} did not finish in {timeout_s}s")

if __name__ == "__main__":
    task_id = create_avatar_video(
        script="Here's the thirty-second version of what we shipped this week.",
        avatar="your-avatar-id",
    )
    outputs = wait_for_video(task_id)
    print("outputs:", outputs)

Due note operative da non saltare quando si usa su larga scala:

• Scarica immediatamente. Come ogni output di task di hiapi, l'URL restituito ha un expireAt e non è adatto come link a lungo termine — non appena il task ha successo, porta i byte (video e .srt) nel tuo storage.
• Non inviare un payload con solo i campi minimi per "controllare lo schema". Poiché tecnicamente solo prompt o audio_url sono obbligatori e gli altri campi usano silenziosamente i valori predefiniti, un payload con solo {"prompt": "test"} non restituirà un 400 — avvierà un render reale e fatturabile. Valida i nomi dei campi confrontandoli con la documentazione o ottenendo una risposta 4xx con un valore volutamente non valido, invece di omettere campi contro l'endpoint reale.

FAQ

Posso usare la mia voce invece del TTS di hiapi? Sì — passa audio_url invece di prompt, fornisci l'URL pubblico della tua registrazione e l'avatar sincronizzerà le labbra su quella traccia invece di sintetizzare il parlato dal testo.

L'opzione caption incide i sottotitoli nel video? No. caption: true restituisce un file .srt separato, sincronizzato con l'audio del video in output. Se vuoi il testo dei sottotitoli sullo schermo, masterizzalo tu stesso come passaggio di post-processing.

Posso controllare la durata della clip? Non direttamente — non c'è un parametro duration. La lunghezza dell'output è determinata dalla lunghezza della sceneggiatura (quando usi prompt) o dalla lunghezza del file audio (quando usi audio_url).

Perché lo sfondo che ho specificato non appare? background funziona solo con gli avatar in stile illustrazione/animazione della libreria HeyGen. Gli avatar fotorealistici mantengono lo sfondo originale della registrazione; in questo caso usa output_format: webm per ottenere un output trasparente e componi tu stesso.

Quali risoluzioni e aspect ratio supporta? Fino a 4K, con opzioni di aspect ratio 9:16, 16:9 e 1:1 — copre dai feed verticali dei brevi video al formato widescreen e quadrato.

Punti chiave

Costruire una pipeline di avatar per brevi video su hiapi si riduce a pochi fatti concreti, non a congetture: il costo è $0,15 per secondo di output (quindi cronometra la sceneggiatura prima di inviare, non dopo), l'output dei sottotitoli è un file .srt allegato che devi masterizzare da solo, la sostituzione dello sfondo funziona solo con avatar in stile illustrazione e il tuo ciclo di polling deve trattare archiving come non terminale, allo stesso modo di handling. Prima di codificare un budget, controlla i numeri attuali nella pagina dei prezzi di hiapi e, per il riferimento completo dei campi, vedi la pagina del modello. Se sei pronto a iniziare, ottieni una API key dalla dashboard e parti da una sceneggiatura breve — un output di 5 secondi basta a confermare che il tuo avatar, l'aspect ratio e la gestione dei sottotitoli funzionino, prima di passare a un intero lotto.