API de avatar parlante: convierte un retrato y un audio en un clip que habla

Usa spicyapi/talking-avatar-v1/talking-avatar para convertir un retrato y de 3 a 60 segundos de voz en MP3 o WAV en un MP4 donde el personaje habla. La grabación aporta las palabras y el ritmo; el retrato aporta el rostro y la escena. Cuesta $0,018 por segundo devuelto, redondeado hacia arriba y con un mínimo de tres segundos, y una frase de 4 a 5 segundos se renderiza en aproximadamente un minuto (una grabación de 60 segundos tarda más). El resultado es compacto, de unos 0,2 megapíxeles a 25 fps, así que sirve para una tarjeta, un feed o una ventana de chat, no para un presentador HD a pantalla completa. Si necesitas HD o un audio más largo, mira la opción Kling Avatar 2.0 al final. Puedes escuchar un resultado real en la página del modelo.

Prepara el retrato y la grabación

El ejemplo usa a Mara, una presentadora de cursos adulta y ficticia con blusa verde azulado. El retrato debe tener:

• un solo rostro nítido, más o menos de frente, con luz uniforme, cabeza y hombros;
• sin manos, pelo, gafas de sol ni micrófono sobre la boca;
• formato JPEG, PNG o WebP, de 10 MB como máximo, con espacio alrededor de la barbilla y el pelo para tu reproductor final.

La grabación es un MP3 o WAV de 90 MB como máximo y de 3 a 60 segundos, con una sola voz y sin música ni voces superpuestas. Recorta los silencios accidentales, pero no la primera ni la última palabra: el silencio cuenta en la duración que pagas. Los archivos fuera del rango de 3–60 segundos se rechazan antes de cualquier cargo.

Ilustración del paso de preparación, no un fotograma de Talking Avatar.

No hay campo script, voice_id ni language. Para otro idioma, graba o genera otro archivo de audio y reutiliza el mismo retrato. Si ya tienes vídeo de un presentador en movimiento y solo quieres reemplazar la voz, usa en su lugar el flujo de sincronización labial.

Entradas

No hay campo para resolución, fotogramas por segundo, duración ni cámara. Una foto 16:9 vuelve a 640×352 y un retrato 3:4 a 400×544.

Tus archivos deben ser accesibles mediante un enlace HTTPS directo. Subirlos es más fiable que apuntar a una página o a un enlace para compartir; las referencias subidas duran poco, así que conserva tus originales.

Cuánto cuesta y por qué el presupuesto es de $1,08

El cargo es la duración devuelta redondeada hacia arriba a segundos enteros, con un mínimo de tres segundos:

El presupuesto y la retención que se aplica al crear la tarea corresponden al tope de 60 segundos: $1,08, sea cual sea la duración de tu audio. Cuando el clip termina, el cargo final se ajusta a la duración real y el resto se libera; una tarea fallida libera toda la retención. Hasta entonces, la retención cuenta contra tu saldo y tus límites de gasto, así que un saldo casi vacío o un límite ajustado puede bloquear incluso un clip de 12 segundos. Pedir un presupuesto no retiene nada.

Pruébalo primero en el Playground

1. Abre la página del modelo Talking Avatar y quédate en la pestaña Playground con la vista Form. Inicia sesión con una cuenta con fondos para ejecutar; el precio aparece una vez que has iniciado sesión.
2. En Input image, suelta el retrato de Mara o pega su enlace con Add URL.
3. En Input audio, añade el MP3 o WAV de la misma manera. Subirlo es más fiable que un enlace.
4. Si quieres, escribe unas palabras de expresión en Prompt (calm and welcoming), añade una Mask para un retrato de grupo o fija un Seed para comparar dos grabaciones.
5. Ejecútalo y reproduce el resultado con sonido al tamaño con el que lo mostrarás.

El Playground envía la misma solicitud que la API, así que un retrato y una grabación que funcionen aquí funcionarán en código. Si aquí cuesta leer la boca, corrige los archivos de origen antes de escribir código.

Después, llámalo desde código

Instala el SDK de Python (pip install spicyapi), define SPICY_API_KEY y ejecuta lo siguiente. Crear la tarea tiene cargo, y la retención es el tope de $1,08 descrito arriba.

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

Los presupuestos, la espera, los reintentos y los errores están en la referencia del SDK de Python y en la guía de tareas asíncronas. Una tarea aceptada no se puede cancelar, así que comprueba el precio antes de ejecutarla. Los enlaces de resultado son temporales, así que guarda tu propia copia, como se explica en cómo hacer duradero el contenido generado.

O deja que lo ejecute un agente

Si un asistente debe crear los clips, dale la CLI o el servidor MCP. Ambos muestran el precio y piden confirmación antes de una llamada de pago. El Skill añade instrucciones sobre cualquiera de los dos.

• CLI. spicyapi ejecuta una tarea desde un terminal (npx @spicyapi/cli funciona sin instalar):

``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 el mismo objeto input de arriba, con las dos URI spicy://.

• Servidor MCP. Añade el servidor MCP a tu asistente y pídele: "Make Mara speak ./mara-intro.mp3 using ./mara.png with Talking Avatar." Llama a spicyapi_upload_file, luego a spicyapi_task_create (que se detiene para que confirmes el precio) y después a 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 instala el Agent Skill, que enseña a un asistente de programación a leer el esquema vigente y a reutilizar las claves de idempotencia en lugar de adivinar. No puede ejecutar tareas por sí solo, así que úsalo con la CLI o MCP.

Corrige los problemas en el origen

Reproduce avatar.mp4 con sonido al tamaño con el que lo mostrarás y compara los ojos, el contorno del rostro y la línea del pelo con el retrato de origen: una boca que se mueve no basta para demostrar que el personaje se mantuvo coherente.

Ilustración de la comprobación de identidad; los retratos impresos son arte construido, no fotogramas de avatar.

Reglas de contenido y cuándo elegir otro modelo

SpicyAPI no añade ningún filtro de seguridad en Talking Avatar v1, y es el propio modelo quien decide qué devuelve; un rostro que no detecta o una imagen rechazada hace fallar la tarea. Usa solo retratos ficticios o de adultos que den su consentimiento.

Kling Avatar 2.0 también acepta un retrato y audio, a 720p ($0,0512 por segundo) o 1080p ($0,1024 por segundo), con clips de hasta unos cinco minutos. Es un modelo filtrado: rechaza los retratos explícitos, así que encaja con clips de presentador y de marca, no con personajes orientados a adultos. Elige Talking Avatar v1 para clips cortos y baratos al tamaño de una tarjeta, y Kling Avatar 2.0 cuando el clip deba verse nítido a tamaño completo o durar más de un minuto.