API de avatar falante: transforme um retrato e um áudio em um clipe que fala

Use spicyapi/talking-avatar-v1/talking-avatar para transformar um retrato e de 3 a 60 segundos de fala em MP3 ou WAV em um MP4 em que o personagem fala. A gravação fornece as palavras e o ritmo; o retrato fornece o rosto e a cena. O preço é de US$ 0,018 por segundo retornado, arredondado para cima e com mínimo de três segundos, e uma fala de 4 a 5 segundos é renderizada em cerca de um minuto (uma gravação de 60 segundos demora mais). O resultado é compacto, cerca de 0,2 megapixel a 25 fps, e serve para um card, um feed ou uma janela de chat, não para um apresentador em HD em tela cheia. Se você precisa de HD ou de áudio mais longo, veja a opção Kling Avatar 2.0 no final. Você pode ouvir um resultado real na página do modelo.

Prepare o retrato e a gravação

O exemplo usa Mara, uma apresentadora de curso adulta e fictícia, de blusa azul-petróleo. O retrato deve ter:

• um único rosto nítido, mais ou menos de frente, com iluminação uniforme, cabeça e ombros;
• nada de mãos, cabelo, óculos escuros ou microfone sobre a boca;
• formato JPEG, PNG ou WebP, de até 10 MB, com espaço em volta do queixo e do cabelo para o seu player final.

A gravação é um MP3 ou WAV de até 90 MB e de 3 a 60 segundos, com uma só voz, sem música nem vozes sobrepostas. Corte silêncios acidentais, mas não a primeira nem a última palavra: o silêncio conta na duração que você paga. Arquivos fora do intervalo de 3 a 60 segundos são rejeitados antes de qualquer cobrança.

Ilustração da etapa de preparação, não um quadro do Talking Avatar.

Não existe campo script, voice_id nem language. Para outro idioma, grave ou gere outro arquivo de áudio e reutilize o mesmo retrato. Se você já tem um vídeo de um apresentador em movimento e só quer trocar a fala, use o fluxo de sincronização labial.

Entradas

Não há campo para resolução, taxa de quadros, duração ou câmera. Uma foto 16:9 volta em 640×352 e um retrato 3:4 em 400×544.

Seus arquivos precisam estar acessíveis por um link HTTPS direto. Enviá-los é mais confiável do que apontar para uma página ou um link de compartilhamento; as referências enviadas duram pouco, então guarde os originais.

Quanto custa e por que a cotação é de US$ 1,08

A cobrança é a duração retornada arredondada para cima em segundos inteiros, com mínimo de três segundos:

A cotação e a retenção feita ao criar a tarefa correspondem ao teto de 60 segundos: US$ 1,08, seja qual for a duração do seu áudio. Quando o clipe termina, a cobrança final é ajustada à duração real e o restante é liberado; uma tarefa que falha libera toda a retenção. Até lá, a retenção conta contra o seu saldo e os seus limites de gasto, então um saldo quase zerado ou um limite apertado pode bloquear até um clipe de 12 segundos. Pedir uma cotação não retém nada.

Experimente primeiro no Playground

1. Abra a página do modelo Talking Avatar e fique na aba Playground na visualização Form. Entre com uma conta com saldo para executar; o preço aparece depois que você entra.
2. Em Input image, solte o retrato da Mara ou cole o link dele com Add URL.
3. Em Input audio, adicione o MP3 ou WAV do mesmo modo. Enviar o arquivo é mais confiável do que um link.
4. Se quiser, digite algumas palavras de expressão em Prompt (calm and welcoming), adicione uma Mask para um retrato em grupo ou defina um Seed para comparar duas gravações.
5. Execute e reproduza o resultado com som no tamanho em que você vai exibi-lo.

O Playground envia a mesma requisição que a API, então um retrato e uma gravação que funcionam aqui funcionarão no código. Se a boca estiver difícil de ler aqui, corrija os arquivos de origem antes de escrever código.

Depois, chame pelo código

Instale o SDK Python (pip install spicyapi), defina SPICY_API_KEY e execute o código abaixo. Criar a tarefa é cobrado, e a retenção é o teto de US$ 1,08 descrito acima.

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

Cotações, espera, novas tentativas e erros estão na referência do SDK Python e no guia de tarefas assíncronas. Uma tarefa aceita não pode ser cancelada, então confira o preço antes de executar. Os links de resultado são temporários, então guarde uma cópia sua, como explicado em como tornar a mídia gerada durável.

Ou deixe um agente executar

Se um assistente deve criar os clipes, dê a ele a CLI ou o servidor MCP. Os dois mostram o preço e pedem confirmação antes de uma chamada paga. O Skill acrescenta instruções por cima de qualquer um deles.

• CLI. spicyapi executa uma tarefa pelo terminal (npx @spicyapi/cli funciona sem 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 contém o mesmo objeto input acima, com as duas URIs spicy://.

• Servidor MCP. Adicione o servidor MCP ao seu assistente e peça: "Make Mara speak ./mara-intro.mp3 using ./mara.png with Talking Avatar." Ele chama spicyapi_upload_file, depois spicyapi_task_create (que para para você confirmar o preço) e então 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 o Agent Skill, que ensina um assistente de programação a ler o esquema atual e a reutilizar chaves de idempotência em vez de adivinhar. Ele não executa tarefas sozinho, então use-o com a CLI ou o MCP.

Corrija os problemas na origem

Reproduza avatar.mp4 com som no tamanho em que você vai exibi-lo e compare olhos, contorno do rosto e linha do cabelo com o retrato de origem: uma boca que se mexe, sozinha, não prova que o personagem se manteve consistente.

Ilustração da verificação de identidade; os retratos impressos são arte construída, não quadros de avatar.

Regras de conteúdo e quando escolher outro modelo

O SpicyAPI não adiciona verificador de segurança ao Talking Avatar v1, e o próprio modelo decide o que volta; um rosto que ele não detecta ou uma imagem rejeitada faz a tarefa falhar. Use apenas retratos fictícios ou de adultos que tenham dado consentimento.

O Kling Avatar 2.0 também recebe um retrato e áudio, em 720p (US$ 0,0512 por segundo) ou 1080p (US$ 0,1024 por segundo), com clipes de até cerca de cinco minutos. É um modelo filtrado: retratos explícitos são recusados, então ele serve para clipes de apresentador e de marca, não para personagens voltados ao público adulto. Escolha o Talking Avatar v1 para clipes curtos e baratos no tamanho de um card, e o Kling Avatar 2.0 quando o clipe precisar ficar nítido em tamanho total ou durar mais de um minuto.