API d'avatar parlant : transformer un portrait et un audio en clip qui parle

Utilisez spicyapi/talking-avatar-v1/talking-avatar pour transformer un portrait et 3 à 60 secondes de voix en MP3 ou WAV en un MP4 où le personnage parle. L'enregistrement fournit les mots et le rythme ; le portrait fournit le visage et la scène. Le tarif est de 0,018 $ par seconde renvoyée, arrondie à la seconde supérieure, avec un minimum de trois secondes, et une phrase de 4 à 5 secondes est rendue en une minute environ (un enregistrement de 60 secondes prend plus de temps). Le résultat est compact, environ 0,2 mégapixel à 25 ips : il convient à une carte, un fil d'actualité ou une fenêtre de chat, pas à un présentateur HD plein écran. Si vous avez besoin de HD ou d'un audio plus long, voyez l'option Kling Avatar 2.0 en fin d'article. Vous pouvez écouter un vrai résultat sur la page du modèle.

Préparer le portrait et l'enregistrement

L'exemple utilise Mara, une présentatrice de cours adulte et fictive en chemisier bleu canard. Le portrait doit être :

• un seul visage net, à peu près de face, éclairé de façon uniforme, tête et épaules ;
• sans mains, cheveux, lunettes de soleil ni microphone devant la bouche ;
• en JPEG, PNG ou WebP, 10 Mo au maximum, avec de la marge autour du menton et des cheveux pour votre lecteur final.

L'enregistrement est un MP3 ou un WAV de 90 Mo au maximum et de 3 à 60 secondes, avec une seule voix, sans musique ni voix qui se chevauchent. Coupez les silences accidentels, mais pas le premier ni le dernier mot : le silence compte dans la durée facturée. Les fichiers hors de la plage 3–60 secondes sont rejetés avant tout débit.

Illustration de l'étape de préparation, pas une image de Talking Avatar.

Il n'existe aucun champ script, voice_id ni language. Pour une autre langue, enregistrez ou générez un autre fichier audio et réutilisez le même portrait. Si vous disposez déjà d'une vidéo d'un présentateur en mouvement et voulez seulement remplacer la voix, utilisez plutôt le workflow de synchronisation labiale.

Entrées

Il n'y a aucun champ pour la résolution, la fréquence d'images, la durée ou la caméra. Une photo 16:9 revient en 640×352 et un portrait 3:4 en 400×544.

Vos fichiers doivent être accessibles par un lien HTTPS direct. Les téléverser est plus fiable que de pointer vers une page ou un lien de partage ; les références téléversées sont de courte durée, conservez donc vos originaux.

Combien cela coûte, et pourquoi le devis est de 1,08 $

Le montant facturé est la durée renvoyée arrondie à la seconde entière, avec un minimum de trois secondes :

Le devis, ainsi que la réserve placée à la création de la tâche, portent sur le plafond de 60 secondes : 1,08 $, quelle que soit la durée de votre audio. Une fois le clip terminé, le montant final est réglé sur la durée réelle et le reste est libéré ; une tâche en échec libère toute la réserve. D'ici là, la réserve compte dans votre solde et vos plafonds de dépenses, de sorte qu'un solde presque vide ou un plafond serré peut bloquer même un clip de 12 secondes. Demander un devis ne réserve rien.

Essayer d'abord dans le Playground

1. Ouvrez la page du modèle Talking Avatar et restez sur l'onglet Playground en vue Form. Connectez-vous avec un compte approvisionné pour lancer ; le prix s'affiche une fois connecté.
2. Sous Input image, déposez le portrait de Mara ou collez son lien avec Add URL.
3. Sous Input audio, ajoutez le MP3 ou le WAV de la même manière. Le téléversement est plus fiable qu'un lien.
4. Saisissez si vous le souhaitez quelques mots d'expression dans Prompt (calm and welcoming), ajoutez un Mask pour un portrait de groupe, ou définissez un Seed pour comparer deux enregistrements.
5. Lancez, puis lisez le résultat avec le son, à la taille à laquelle vous l'afficherez.

Le Playground envoie la même requête que l'API : un portrait et un enregistrement qui fonctionnent ici fonctionneront dans le code. Si la bouche est difficile à lire ici, corrigez les fichiers sources avant d'écrire du code.

Puis l'appeler depuis le code

Installez le SDK Python (pip install spicyapi), définissez SPICY_API_KEY et exécutez ce qui suit. La création de la tâche est facturée, et la réserve est le plafond de 1,08 $ décrit plus haut.

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")

Les devis, l'attente, les nouvelles tentatives et les erreurs sont détaillés dans la référence du SDK Python et le guide des tâches asynchrones. Une tâche acceptée ne peut pas être annulée : vérifiez donc le prix avant de lancer. Les liens de résultat sont temporaires ; conservez votre propre copie, comme expliqué dans rendre durables les médias générés.

Ou laisser un agent s'en charger

Si un assistant doit produire les clips, donnez-lui la CLI ou le serveur MCP. Tous deux affichent le prix et demandent votre confirmation avant un appel payant. Le Skill ajoute des instructions par-dessus l'un ou l'autre.

• CLI. spicyapi exécute une tâche depuis un terminal (npx @spicyapi/cli fonctionne sans installation) :

``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 contient le même objet input que ci-dessus, avec les deux URI spicy://.

• Serveur MCP. Ajoutez le serveur MCP à votre assistant, puis demandez : « Make Mara speak ./mara-intro.mp3 using ./mara.png with Talking Avatar. » Il appelle spicyapi_upload_file, puis spicyapi_task_create (qui s'arrête pour que vous confirmiez le prix), puis 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 installe l'Agent Skill, qui apprend à un assistant de code à lire le schéma à jour et à réutiliser les clés d'idempotence au lieu de deviner. Il ne peut pas exécuter de tâches seul : utilisez-le avec la CLI ou MCP.

Corriger les problèmes à la source

Lisez avatar.mp4 avec le son, à la taille d'affichage prévue, et comparez les yeux, le contour du visage et la ligne des cheveux avec le portrait source : une bouche qui bouge ne prouve pas à elle seule que le personnage est resté cohérent.

Illustration de la vérification d'identité ; les portraits imprimés sont des visuels fabriqués, pas des images d'avatar.

Règles de contenu et quand choisir un autre modèle

SpicyAPI n'ajoute aucun filtre de sécurité sur Talking Avatar v1, et c'est le modèle lui-même qui décide de ce qui revient ; un visage qu'il ne détecte pas ou une image rejetée fait échouer la tâche. N'utilisez que des portraits fictifs ou d'adultes consentants.

Kling Avatar 2.0 accepte lui aussi un portrait et un audio, en 720p (0,0512 $ par seconde) ou en 1080p (0,1024 $ par seconde), avec des clips allant jusqu'à environ cinq minutes. C'est un modèle filtré : les portraits explicites sont refusés, il convient donc aux clips de présentateur et de marque plutôt qu'aux personnages destinés à un public adulte. Choisissez Talking Avatar v1 pour des clips courts et peu coûteux à la taille d'une carte, et Kling Avatar 2.0 quand le clip doit rester net en plein écran ou durer plus d'une minute.