Fluxo de trabalho de API de troca de rosto com IA: envios autorizados, tarefas assíncronas e entrega confiável

Comparar fotos de referência e cor antes da troca.

No SpicyAPI, o Face Swap é uma família de endpoints sem censura que recebem duas imagens (ou uma imagem e um clipe), sem prompt e sem máscara. Este guia mostra qual endpoint chamar, como testar primeiro no Playground e depois pelo código ou por um agente, o que verificar na saída e como manter o resultado depois que a plataforma o apagar.

Escolher o endpoint para a tarefa

Comece pelo Face Swap a $0,013. Passe para o Pro quando o rosto trocado parecer mais liso ou mais nítido do que o resto do quadro, e para o Plus quando as duas fotos tiverem tons de pele ou cores de luz claramente diferentes. 200 variantes de avatar custam $2,60 no Face Swap e $32 no Pro, então teste o par mais difícil nos dois. O Plus tem um campo prompt que não tem efeito algum, então deixe-o de fora e coloque os óculos ou a expressão na foto de destino.

O Video Face Swap cobra o clipe de origem em blocos inteiros de 10 segundos, então um clipe de 12 segundos é cobrado como 20 segundos ($0,52) e um de 40 segundos como $1,04. No envio, a estimativa de 40 segundos ($1,04) fica retida e a diferença é liberada quando a tarefa é liquidada. Corte até um limite de bloco antes de enviar.

O que os endpoints fazem com rostos reais

Estes endpoints são listados como sem censura: o SpicyAPI não adiciona varredura de rosto por requisição nem verificação de pessoa real. As falhas costumam ser da entrada (nenhum rosto detectável, um arquivo inacessível), embora um modelo específico ainda possa recusar uma requisição. A política de uso aceitável proíbe falsidade de identidade, uso íntimo ou sexualizado sem consentimento da semelhança de uma pessoa real e qualquer coisa que envolva menores; após uma denúncia, o SpicyAPI pode remover os ativos armazenados e suspender o acesso. Uma foto pública ou um relacionamento anterior não são consentimento. O registro de consentimento é seu e deve ficar antes do botão de envio:

• O usuário conectado confirma que tem a permissão da pessoa retratada para as duas imagens e para este uso; guarde a confirmação junto com o projeto (quem, qual ativo, qual uso, quando).
• Nenhuma imagem de menores e nenhum uso que finja ser uma pessoa real para enganar.

Guarde isso como registros de produto, não em prompts, eventos de análise nem logs.

Preparar entradas que não vão falhar

Não há ajuste de intensidade a calibrar, então um resultado ruim significa outro par de entradas.

• Rostos frontais, grandes e nítidos. Ângulos de perfil fortes, borrão de movimento, oclusão densa (mãos, máscaras, óculos de sol grandes) e rostos muito pequenos degradam a transferência ou fazem a requisição falhar. Um rosto de referência grande, nítido e frontal dá o melhor resultado.
• A mesma direção de luz. A troca não reilumina o alvo, então uma referência iluminada do outro lado aparece como uma emenda na linha da mandíbula. Combine direção e tom de pele aproximado, ou escolha outra referência. O Plus só harmoniza o tom de pele; não corrige divergência de direção de luz.
• Um rosto por imagem. Em fotos de grupo, Face Swap e Video Face Swap aceitam face_mapping: até 10 entradas, cada uma emparelhando um rosto de referência com um rosto de destino, numeradas a partir de 0 na ordem de detecção. Reconfira a numeração sempre que mudar uma imagem. Plus e Pro assumem um único rosto; corte antes.

``json "face_mapping": [{ "reference_face_index": 0, "target_face_index": 1 }] ``

Isso troca o rosto de referência 0 pelo segundo rosto encontrado no destino. Deixe o campo de fora para trocar um único rosto.

• Links diretos para arquivos. URLs de imagem precisam resolver para o arquivo sem login. Em vídeo, uma página que reproduz o clipe devolve HTML em vez de clipe, e a chamada falha com a cobrança reembolsada; envie o arquivo.
• Os papéis não são intercambiáveis. image_url é a imagem que é alterada; reference_image_url fornece o rosto. Trocá-los é uma requisição válida com outro resultado e sem erro, então uma troca na direção errada parece um defeito do modelo.

Limites para vídeo: MP4 até 90 MB e de 3 a 40 segundos, imagem de referência JPG, PNG ou WEBP até 10 MB. Mantenha o rosto grande no quadro e não virado por muito tempo. O endpoint funciona melhor com uma pessoa na tela; para um clipe com várias pessoas, adicione face_mapping (mesmo formato acima, numerado na ordem de detecção) ou corte até a pessoa.

Teste primeiro no Playground

Abra a página de tarefa do Face Swap e use a aba Playground (configurar, estimar, executar). Informe a imagem de destino e a imagem do rosto de referência, confira a estimativa de preço para as suas configurações e execute. Teste aqui o par mais difícil antes de escrever código: se o resultado estiver errado no Playground, estará errado pela API, e a correção é outro par de entradas. Head Swap tem a mesma aba para trocas de cabeça inteira.

Depois chame pelo código

Instale o SDK Python (pip install spicyapi), defina SPICY_API_KEY no ambiente e execute:

import json
import uuid
from pathlib import Path
from spicyapi import SpicyClient, output_assets

client = SpicyClient()  # reads SPICY_API_KEY from the environment
job_file = Path("avatar-8841-layout-02-v1.json")  # keep this file to resume this job

if job_file.exists():
    job = json.loads(job_file.read_text())
else:
    target = client.upload_file("./layout-02.png")
    face = client.upload_file("./approved-portrait.png")
    job = {
        "key": str(uuid.uuid4()),
        "input": {"image_url": target["uri"], "reference_image_url": face["uri"],
                  "style": "realistic", "seed": 4242},
    }
    job_file.write_text(json.dumps(job))  # persist the exact key and payload BEFORE submit

if "taskId" not in job:
    task = client.create_task(
        model="spicyapi/face-swap-v1/edit", input_data=job["input"],
        idempotency_key=job["key"],
    )
    job["taskId"] = task["taskId"]
    job_file.write_text(json.dumps(job))

print("Resume task:", job["taskId"], flush=True)
final = client.wait_for_terminal(job["taskId"])
if final["state"] != "succeeded":
    raise RuntimeError(f"Task {job['taskId']} ended as {final['state']}")
assets = output_assets(final)
if not assets or any(a.get("pending") or a.get("unavailable") or not a.get("url") for a in assets):
    raise RuntimeError(f"Task {job['taskId']} has no ready output; check this task, not a new run")
print(assets[0]["url"])  # copy it to your own storage now

Execute um processo por arquivo de tarefa. Se a espera expirar, execute de novo com o mesmo arquivo para retomar a tarefa salva. Se o próprio envio expirou antes de retornar um ID, guarde o arquivo e concilie essa requisição antes de tentar de novo; a proteção de idempotência não é permanente. Use um novo nome de arquivo de tarefa apenas quando quiser uma nova requisição paga.

Uploads, espera, erros e novas tentativas estão no guia de Subject Swap e na referência do SDK Python. O Video Face Swap usa spicyapi/face-swap-video-v1/video-edit com video_url e reference_image_url.

Ou deixar um agente executar o trabalho

Se um assistente deve fazer as trocas por você, dê a ele a CLI ou o servidor MCP. Ambos mostram o preço e pedem confirmação antes de uma chamada paga. O Skill acrescenta instruções a qualquer um dos dois.

• CLI. spicyapi executa uma tarefa a partir de um terminal ou script (npx @spicyapi/cli funciona sem instalação):

``bash spicyapi files upload ./layout-02.png # prints a spicy:// URI SWAP_REQUEST_KEY="$(python3 -c 'import uuid; print(uuid.uuid4())')" printf 'Save this request key: %s\n' "$SWAP_REQUEST_KEY" spicyapi tasks create --model spicyapi/face-swap-v1/edit \ --input-file input.json --idempotency-key "$SWAP_REQUEST_KEY" --wait ``

input.json contém o mesmo objeto input acima, com os URIs spicy://. Este bloco inicia uma tarefa nova. Guarde a chave e o ID de tarefa impressos; depois de um tempo limite, retome essa tarefa em vez de executar o bloco de novo com uma chave nova.

• Servidor MCP. Adicione o servidor MCP ao seu assistente e então pergunte: "Swap the face in ./layout-02.png for the one in ./approved-portrait.png with Face Swap." Ele chama spicyapi_upload_file, depois spicyapi_task_create (que para para você confirmar o preço) e depois 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, reutilizar chaves de idempotência e salvar resultados em vez de adivinhar. Ele não executa tarefas sozinho, então use-o com a CLI ou o MCP.

O registro de consentimento e copiar os resultados para o seu próprio armazenamento valem para as chamadas de um agente exatamente como valem para as suas.

Revise antes de dar por concluído

succeeded significa que a geração terminou. Antes de baixar, confirme que o ativo tem uma URL utilizável e que nem pending nem unavailable são verdadeiros; enquanto pending for verdadeiro ou a URL estiver faltando, continue consultando a mesma tarefa. Prontidão para entrega ainda não significa que a imagem foi aprovada. Em vídeo, examine cortes e movimentos rápidos, não só o primeiro quadro. Uma pontuação de similaridade é um sinal de diagnóstico, não consentimento nem aprovação de publicação.

Duas verificações que mudam o que você faz em seguida:

• O cabelo faz parte do design (um personagem de jogo, um mascote). O Face Swap mantém o penteado do destino, então o novo rosto fica sob o cabelo antigo. Use Head Swap, com uma imagem fixa da ficha de personagem como referência, e compare cada saída com a ficha: um rosto que deriva sobre uma composição estável é um problema de identidade, o contrário é um problema de enquadramento, e uma nova tentativa só resolve um dos dois.
• Um retrato em vários layouts. Execute Face Swap uma vez por layout com a mesma referência e o mesmo seed. Aceite uma saída quando o rosto for reconhecível contra o retrato no corte que você vai publicar, quando os óculos e a linha do cabelo não tiverem derivado e quando nenhuma pessoa extra aparecer; guarde a revisão da referência, a revisão do destino e o ID da tarefa junto dela.

Entregar: copie o resultado você mesmo

Fontes enviadas são apagadas depois de um dia e resultados depois de no máximo 14 dias (retention.outputsExpireAt tem o horário exato). Baixe o resultado e guarde você mesmo; o link do resultado dura cerca de 20 minutos. Veja o guia de retenção.

Quando dá errado

FAQ

A API vai recusar o rosto de uma pessoa real?

O SpicyAPI não verifica: não há checagem de pessoa real nem varredura por requisição, e as falhas costumam ser da entrada. Um modelo específico ainda pode recusar, e a política de uso aceitável proíbe falsidade de identidade, uso íntimo sem consentimento e menores. Monte você mesmo o registro de permissões.

Posso enviar um vídeo e uma imagem em uma única chamada?

Sim, no Video Face Swap: um MP4 e uma foto de referência. Para várias pessoas em um clipe, use face_mapping ali, ou o fluxo de duas etapas do Video Head Swap quando precisar de cabeças inteiras.

API hospedada ou troca open source auto-hospedada?

O endpoint hospedado custa $0,013 por imagem e elimina o provisionamento de GPU e a manutenção do modelo. A auto-hospedagem troca as taxas por imagem por custos de GPU e operação; se fica mais barato depende da vazão e da utilização. Um volume alto e constante pode diluir esses custos por mais imagens, mas você continua mantendo os controles de consentimento e retenção.

Isto é igual a uma API geral de edição de imagens?

Não. Um endpoint de troca recebe duas imagens (ou uma imagem e um clipe), sem prompt e sem máscara, e cada endpoint decide o que fica do destino: o Face Swap mantém o cabelo, o Head Swap o substitui. O mesmo par de entradas pode falhar na revisão de forma diferente em cada um, então escolha o endpoint primeiro.

Devo manter os retratos originais junto com a saída?

Só se você tiver um motivo claro e uma política de retenção declarada. As fontes enviadas no SpicyAPI são apagadas depois de um dia de qualquer forma, então guarde os IDs de revisão da referência e do destino e o ID da tarefa como linhagem, em vez de uma cópia permanente de cada retrato.

Preciso de webhooks ou o polling basta?

O polling sozinho funciona e é o caminho de recuperação: leia a cada poucos segundos, ou acrescente wait (até 60 s) no createTask para trocas curtas de imagem. Acrescente um webhook para reduzir a latência, guarde cada evento uma única vez e trate o polling como a conciliação das callbacks perdidas.

O que você precisa saber responder

Um recurso de troca de rosto ganha confiança quando o seu time consegue dizer quais imagens foram usadas, quais revisões entraram, se a tarefa foi aceita uma única vez, por que um resultado foi entregue e como ele é removido. Registros de consentimento, chaves de idempotência, o seu próprio armazenamento e uma etapa de revisão são o que produz essas respostas.