Introdução
Leva os traços do rosto de uma imagem para a pessoa de outra. Só os traços viajam: penteado, linha do cabelo, silhueta da cabeça, pose, roupa, luz e fundo da imagem de destino continuam como estavam, e é isso que faz o resultado se encaixar dentro da foto original em vez de ficar colado por cima.
Face Swap Pro é o nível de precisão da linha Face Swap. O motor localiza sozinho os pontos-chave do rosto nas duas fotos e mapeia um conjunto sobre o outro, e depois nada mais é aplicado ao resultado. A requisição inteira são duas URLs de imagem — image_url para a foto que vai mudar, reference_image_url para o rosto — enviadas para spicyapi/face-swap-pro-v1/edit. A chamada é assíncrona: ela devolve um id de tarefa, você consulta essa tarefa e cada requisição devolve uma imagem, cobrada por imagem gerada.
Recursos e destaques
O motor posiciona o rosto pelos pontos-chave
O Pro foi feito para trabalho de precisão. Em vez de copiar uma região, ele localiza os pontos-chave do rosto nas duas fotos e mapeia um conjunto sobre o outro, e assim olhos, nariz e boca caem onde a geometria do rosto de destino os coloca. Neste endpoint a detecção é automática: você envia duas imagens e mais nada. Também não há etapa de embelezamento depois, então poros, linhas finas e granulação continuam lá e o rosto tem a mesma nitidez de todo o resto. É também por isso que um resultado pode parecer menos lisonjeiro que uma troca com filtro: precisão e lisonja não são o mesmo objetivo.
Duas URLs de imagem e nada mais para errar
É o único endpoint de troca de rosto deste catálogo que recebe apenas as duas imagens: não há prompt para escrever, região para pintar, intensidade para ajustar nem seed para fixar. Isso elimina toda a classe de erros que vem de instruções ambíguas e deixa o processamento em lote trivial, porque uma lista de pares passa sem nenhuma decisão item a item. Chaves desconhecidas são recusadas em vez de ignoradas, então um nome de campo digitado errado falha no envio em vez de cair silenciosamente num valor padrão. A única coisa que realmente importa é qual URL vai em qual campo: os dois não são simétricos, e trocá-los ainda gera uma requisição válida, com um resultado completamente diferente.
A foto de destino sobrevive à troca
| Vem da referência | Fica com o destino |
|---|---|
| Olhos, nariz, boca, sobrancelhas | Penteado, linha do cabelo, silhueta da cabeça |
| As proporções do próprio rosto | Pose, olhar, corpo, roupa |
| O detalhe da pele dentro da região do rosto | Fundo, enquadramento, luz, granulação |
Não há proporção nem resolução para definir, porque a imagem não é gerada de novo: uma região de uma foto existente é substituída. É isso que torna o endpoint utilizável numa foto que você já aprovou: nada fora do rosto volta a ser discutido.
Parâmetros da requisição
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
image_url | Sim | A imagem que muda. pelo menos 1 caracteres |
reference_image_url | Sim | A imagem que fornece os traços do rosto. Só o rosto é aproveitado, não o formato da cabeça nem o cabelo, então o enquadramento, o fundo e o figurino dessa foto são ignorados. pelo menos 1 caracteres |
face_enhance | Não | Aplica uma etapa de melhoria no rosto trocado para deixá-lo em resolução mais alta. Desligado por padrão. Valor padrão: |
Preços
$0.16 / imagem
Casos de uso
Imagens editoriais e de campanha que vão para impressão
Um rosto alisado desmorona no tamanho de impressão: ao lado de uma roupa e de um fundo nítidos, a pele parece plástico. Manter a textura original faz a imagem se sustentar quando alguém olha de perto, e não só na miniatura.
Trocar a pessoa de uma foto já aprovada
Luz, pose e cenário já funcionam, e gerar a imagem inteira de novo colocaria tudo isso em jogo outra vez. Leve só um rosto para a foto e tudo o que você aprovou fica exatamente onde estava.
Personagens consistentes em uma série
Gere as cenas com qualquer modelo e depois leve um mesmo rosto para todas, para a série ser lida como a mesma pessoa. Cabelo e roupa continuam os de cada imagem de destino, então a variação que você gerou sobrevive à passada.
Imagens sem censura, em que o limite é o consentimento e não o tema
A SpicyAPI não acrescenta nenhum filtro de conteúdo próprio e não pede sinalizador de conteúdo, então o corpo da requisição são sempre os mesmos dois campos, mostre o quadro o que mostrar. O que não relaxa é a autorização: é preciso o consentimento explícito e informado da pessoa retratada para aquela semelhança específica naquele material específico, e o consentimento nunca é presumido porque uma fotografia é pública.
Guia de prompt e dicas práticas
Não há prompt, então o ajuste acontece antes da chamada
Na maioria dos endpoints de imagem, você reescreve uma frase quando o resultado decepciona. Aqui não: a requisição são duas URLs, então as únicas variáveis são as fotos que você envia. Isso deixa cada iteração fácil de entender — troque uma imagem, mantenha a outra e você sabe exatamente o que mudou —, mas também significa que um par ruim não se salva com uma instrução melhor.
Escolher o destino e a referência
image_url é a foto que vai mudar; reference_image_url fornece o rosto. As duas devem mostrar um único rosto bem visível, mais ou menos de frente, em foco e grande o bastante no quadro para os traços serem legíveis, em JPEG, PNG ou WebP. Recorte antes uma foto de grupo até ficar uma pessoa só. O controle mais útil é a direção da luz: escolha uma referência iluminada mais ou menos do mesmo lado que o destino, porque a troca não muda a luz do destino e uma diferença aparece como uma emenda na linha do queixo.
Quando o resultado não sai como você queria
| O que você vê | O que mudar primeiro |
|---|---|
| Uma emenda no queixo ou no pescoço | Use uma referência iluminada da mesma direção |
| Traços moles ou aproximados | Use uma referência com o rosto maior e mais nítido |
| A pessoa errada mudou | Recorte o destino até ficar uma pessoa só |
| A requisição falhou por completo | Confira se as duas URLs ainda devolvem um arquivo de imagem |
| Menos polido que outra ferramenta de troca | Esperado — não há retoque; aplique o seu depois |
Escolher o endpoint certo
| O que você precisa | Endpoint |
|---|---|
| Precisão nos pontos do rosto e textura original, sem ajustes | Este endpoint |
| Ajuste de tom de pele e escolha do formato de arquivo | Face Swap Plus |
| A troca simples com seed, sem nunca mexer no cabelo | Face Swap |
| A cabeça inteira, com cabelo | Head Swap |
| Um rosto ao longo de um clipe em movimento | Video Face Swap |
Rodar em lote
Como nada é decidido item a item, um lote é um laço sobre pares. Envie cada chamada de criação com um Idempotency-Key e guarde o id da tarefa junto ao registro que a disparou; se uma conexão cair, repetir a requisição com a mesma chave devolve a tarefa original em vez de iniciar uma segunda com uma segunda cobrança. Consulte a cada poucos segundos e copie cada resultado para o seu próprio armazenamento — arquivos gerados são apagados depois de 14 dias, e imagens de origem enviadas, depois de um.
Início rápido da API
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "spicyapi/face-swap-pro-v1/edit",
"input": {
"image_url": "https://example.com/reference.png",
"reference_image_url": "https://example.com/reference.png"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
Consulte a referência da API para autenticação, esquema completo, polling e tratamento de erros.
