API avatar parlante: trasforma un ritratto e un audio in una clip che parla

Usa spicyapi/talking-avatar-v1/talking-avatar per trasformare un ritratto e da 3 a 60 secondi di voce in MP3 o WAV in un MP4 in cui il personaggio parla. La registrazione fornisce le parole e i tempi; il ritratto fornisce il volto e la scena. Costa $0,018 per secondo restituito, arrotondato per eccesso e con un minimo di tre secondi, e una frase di 4–5 secondi viene generata in circa un minuto (una registrazione di 60 secondi richiede più tempo). Il risultato è compatto, circa 0,2 megapixel a 25 fps, quindi va bene per una scheda, un feed o una finestra di chat, non per un presentatore HD a schermo intero. Se ti serve l'HD o un audio più lungo, guarda l'opzione Kling Avatar 2.0 alla fine. Puoi ascoltare un risultato reale nella pagina del modello.

Prepara il ritratto e la registrazione

L'esempio usa Mara, una presentatrice di corsi adulta e fittizia con una camicetta verde petrolio. Il ritratto dovrebbe essere:

• un solo volto nitido, più o meno frontale, illuminato in modo uniforme, testa e spalle;
• senza mani, capelli, occhiali da sole o microfono davanti alla bocca;
• in JPEG, PNG o WebP, al massimo 10 MB, con spazio attorno a mento e capelli per il tuo player finale.

La registrazione è un MP3 o WAV di al massimo 90 MB e da 3 a 60 secondi, con una sola voce, senza musica né voci sovrapposte. Taglia i silenzi accidentali, ma non la prima né l'ultima parola: il silenzio conta nella durata che paghi. I file fuori dall'intervallo 3–60 secondi vengono rifiutati prima di qualsiasi addebito.

Illustrazione del passaggio di preparazione, non un fotogramma di Talking Avatar.

Non esistono i campi script, voice_id o language. Per un'altra lingua, registra o genera un altro file audio e riutilizza lo stesso ritratto. Se hai già un video di un presentatore in movimento e vuoi solo sostituire la voce, usa invece il flusso di lip sync.

Input

Non c'è alcun campo per risoluzione, frame rate, durata o camera. Una foto 16:9 torna a 640×352 e un ritratto 3:4 a 400×544.

I tuoi file devono essere raggiungibili tramite un link HTTPS diretto. Caricarli è più affidabile che puntare a una pagina o a un link di condivisione; i riferimenti caricati durano poco, quindi conserva gli originali.

Quanto costa e perché il preventivo è di $1,08

L'addebito è la durata restituita arrotondata per eccesso a secondi interi, con un minimo di tre secondi:

Il preventivo e il blocco applicato alla creazione dell'attività corrispondono al tetto di 60 secondi: $1,08, qualunque sia la durata del tuo audio. Quando la clip è pronta, l'addebito finale viene regolato sulla durata reale e il resto viene rilasciato; un'attività fallita rilascia l'intero blocco. Fino ad allora il blocco conta sul tuo saldo e sui limiti di spesa, quindi un saldo quasi esaurito o un limite stretto possono bloccare anche una clip di 12 secondi. Richiedere un preventivo non blocca nulla.

Prova prima nel Playground

1. Apri la pagina del modello Talking Avatar e resta nella scheda Playground con la vista Form. Per eseguire, accedi con un account con fondi; il prezzo compare una volta effettuato l'accesso.
2. In Input image, trascina il ritratto di Mara o incolla il suo link con Add URL.
3. In Input audio, aggiungi l'MP3 o il WAV allo stesso modo. Caricarlo è più affidabile di un link.
4. Se vuoi, scrivi poche parole di espressione in Prompt (calm and welcoming), aggiungi una Mask per un ritratto di gruppo o imposta un Seed per confrontare due registrazioni.
5. Esegui, poi riproduci il risultato con l'audio alla dimensione con cui lo mostrerai.

Il Playground invia la stessa richiesta dell'API, quindi un ritratto e una registrazione che funzionano qui funzioneranno anche nel codice. Se qui la bocca è difficile da leggere, correggi i file di partenza prima di scrivere codice.

Poi chiamalo dal codice

Installa l'SDK Python (pip install spicyapi), imposta SPICY_API_KEY ed esegui quanto segue. La creazione dell'attività è addebitata e il blocco è il tetto di $1,08 descritto sopra.

import shutil
import urllib.request
import uuid

from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment

portrait = client.upload_file("./mara.png")      # local files become spicy:// URIs
speech = client.upload_file("./mara-intro.mp3")

task = client.create_task(
    model="spicyapi/talking-avatar-v1/talking-avatar",
    input_data={
        "image_url": portrait["uri"],
        "audio_url": speech["uri"],
        "prompt": "calm and welcoming",
        "seed": 42,
    },
    idempotency_key=str(uuid.uuid4()),  # new key per new request; reuse only to retry the same one
)

final = client.wait_for_terminal(task["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {task['taskId']} ended as {final['state']}")

url = output_assets(final)[0]["url"]
request = urllib.request.Request(url, headers={"User-Agent": "avatar-example/1.0"})  # default Python clients can get a 403
with urllib.request.urlopen(request, timeout=60) as response, open("avatar.mp4", "wb") as target:
    shutil.copyfileobj(response, target)
print("Saved avatar.mp4")

Preventivi, attesa, nuovi tentativi ed errori sono descritti nel riferimento dell'SDK Python e nella guida alle attività asincrone. Un'attività accettata non può essere annullata, quindi controlla il prezzo prima di eseguirla. I link dei risultati sono temporanei, quindi conserva una tua copia, come spiegato in rendere duraturi i contenuti generati.

Oppure lascia che lo esegua un agente

Se un assistente deve creare le clip, dagli la CLI o il server MCP. Entrambi mostrano il prezzo e chiedono conferma prima di una chiamata a pagamento. Lo Skill aggiunge istruzioni sopra l'uno o l'altro.

• CLI. spicyapi esegue un'attività da terminale (npx @spicyapi/cli funziona senza installazione):

``bash spicyapi files upload ./mara.png # prints a spicy:// URI; repeat for the audio spicyapi tasks create --model spicyapi/talking-avatar-v1/talking-avatar \ --input-file input.json --wait ``

input.json contiene lo stesso oggetto input di sopra, con i due URI spicy://.

• Server MCP. Aggiungi il server MCP al tuo assistente, poi chiedi: "Make Mara speak ./mara-intro.mp3 using ./mara.png with Talking Avatar." Chiama spicyapi_upload_file, poi spicyapi_task_create (che si ferma per la tua conferma del prezzo) e infine spicyapi_task_wait.

``json { "mcpServers": { "spicyapi": { "command": "npx", "args": ["--yes", "--package=@spicyapi/mcp", "spicyapi-mcp"], "env": { "SPICY_API_KEY": "YOUR_SPICY_API_KEY" } } } } ``

• Skill. npx skills add spicyapi-ai/spicy-skill installa l'Agent Skill, che insegna a un assistente di programmazione a leggere lo schema aggiornato e a riutilizzare le chiavi di idempotenza invece di tirare a indovinare. Non può eseguire attività da solo, quindi usalo con la CLI o MCP.

Correggi i problemi alla fonte

Riproduci avatar.mp4 con l'audio alla dimensione con cui lo mostrerai e confronta occhi, contorno del viso e attaccatura dei capelli con il ritratto di partenza: una bocca che si muove da sola non dimostra che il personaggio sia rimasto coerente.

Illustrazione del controllo dell'identità; i ritratti stampati sono grafica costruita, non fotogrammi di avatar.

Regole sui contenuti e quando scegliere un altro modello

SpicyAPI non aggiunge alcun controllo di sicurezza su Talking Avatar v1, ed è il modello stesso a decidere cosa restituire; un volto che non riesce a rilevare o un'immagine rifiutata fanno fallire l'attività. Usa solo ritratti fittizi o di adulti consenzienti.

Kling Avatar 2.0 accetta anch'esso un ritratto e un audio, a 720p ($0,0512 al secondo) o 1080p ($0,1024 al secondo), con clip fino a circa cinque minuti. È un modello filtrato: i ritratti espliciti vengono rifiutati, quindi si adatta a clip da presentatore e di brand più che a personaggi rivolti a un pubblico adulto. Scegli Talking Avatar v1 per clip brevi ed economiche a dimensione di scheda, e Kling Avatar 2.0 quando la clip deve essere nitida a schermo intero o durare più di un minuto.