Introdução
Leva um rosto de uma imagem para a pessoa de outra e, no caminho, ajusta o tom de pele entre as duas. Quanto é levado é decidido para você: o motor funde só o rosto ou a cabeça inteira, o que parecer mais natural para aquele par, então a linha do cabelo nem sempre fica intacta. Pose, roupa, luz e fundo do destino continuam como estavam.
Face Swap Plus é o nível ajustável da linha Face Swap. Além das duas imagens, ele aceita uma instrução curta por escrito, um formato de arquivo de saída e um seed, e é enviado para spicyapi/face-swap-v1-plus/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, seja qual for o formato pedido.
Recursos e destaques
O tom de pele é ajustado para você
O lugar onde uma troca de rosto mais se entrega é a borda: uma referência fotografada com luz quente jogada num destino com luz fria deixa um halo em volta do queixo e um pescoço que já não pertence à cabeça. Este motor ajusta o tom entre as duas fotos durante a troca, então um par parecido, mas não idêntico, costuma encaixar sem correção de cor manual depois. A direção da luz continua importando — um rosto iluminado do outro lado ainda parece errado —, mas a diferença mais comum já sai resolvida.
A profundidade da fusão é decidida par a par
É uma troca de cabeça inteligente: para cada par, o motor julga se fundir só o rosto ou a cabeça inteira fica mais natural, e não há ajuste para forçar uma coisa ou outra. Essa é a diferença prática em relação ao resto da linha, onde a linha do cabelo sempre fica com o destino. É também por isso que um resultado pode voltar com a linha do cabelo um pouco diferente do esperado: o motor decidiu que a fusão completa era a mais convincente das duas.
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. pelo menos 1 caracteres |
prompt | Não | Opcional, mas construa como se ele não existisse. no máximo 200 caracteres |
output_format | Não | O formato de arquivo da imagem devolvida. |
output_quality | Não | Qualidade de imagem solicitada para o resultado, de 10 a 100 (padrão 95). Não muda o preço. |
seed | Não | Reutilize uma semente para comparar duas execuções sobre o mesmo par de imagens contra um sorteio idêntico, de modo que a única coisa que se mexe seja o que você mudou. |
Preços
$0.16 / imagem
Casos de uso
Fluxos em massa de avatares e fotos de perfil
Uma lista de pares destino-referência passa pelo endpoint de forma programática, uma chamada por par. Fixe um seed por par quando uma nova tentativa precisar ser comparável à primeira, e escolha WebP quando os resultados forem direto para a web.
Recursos para o consumidor atrás de um formulário de envio
A interação é uma foto do usuário e uma imagem que você fornece. O usuário não tem nada para configurar nem prompt para escrever, então o recurso inteiro é um campo de formulário e um processo em segundo plano.
Catálogos e templates
Um mesmo rosto de referência aplicado a um conjunto de imagens preparadas dá uma série coerente sem gerar nenhuma de novo. O ajuste de formato de saída entrega os arquivos no formato que o seu fluxo já espera; qualquer acessório que um template exija precisa estar na imagem antes da troca.
Imagens sem censura, em que o limite é o consentimento e não o tema
A SpicyAPI não adiciona nenhum filtro de conteúdo próprio nem pede indicador de maturidade, então o corpo da requisição traz os mesmos campos, mostre a imagem o que mostrar. O que não se afrouxa é a autorização: você precisa do consentimento explícito e informado da pessoa retratada para aquele rosto específico naquele material específico, e uma foto ser pública nunca significa consentimento.
Guia de prompt e dicas práticas
O campo de instrução não faz nada aqui
O modelo de base aceita prompt, com limite de 200 caracteres, mas não conseguimos fazer ele mudar nada.
| O que enviamos | O que voltou |
|---|---|
add mirrored aviator sunglasses | Sem óculos de sol; igual a não enviar nada |
wearing black sunglasses | Sem óculos de sol; igual a não enviar nada |
restyle the hair into a sleek straight bob | Cabelo sem mudança |
soften the expression into a faint half smile | Expressão sem mudança |
a wide open-mouthed laugh | Expressão sem mudança |
Cinco chamadas reais em 20 de setembro de 2026, cada uma comparada com a mesma requisição com o campo vazio. Não há erro nem aviso, então a resposta não mostra que o valor foi ignorado. Monte sem ele: se precisar de um acessório ou de outra expressão, coloque-os na imagem de destino antes da troca.
O que o motor decide por você
Duas execuções neste endpoint voltaram com decisões opostas, e é o jeito mais claro de ver isso:
| Destino | O que foi levado |
|---|---|
| Um rabo de cavalo preto bem preso | A cabeça inteira — o cabelo ruivo da referência veio junto com os traços |
| Cabelo molhado penteado para trás | Só o rosto — o cabelo do destino ficou exatamente como foi fotografado |
Se você precisava de um acessório ou de outra expressão
O campo de instrução não leva você até lá, então a mudança precisa existir antes da troca:
| O que você queria | Onde fazer isso |
|---|---|
| Óculos de sol, chapéu, joias | Coloque na pessoa da imagem de destino antes de chamar este endpoint |
| Outra expressão ou outro penteado | Fotografe ou gere a imagem de destino assim; a troca mantém os dois |
Escolher o formato de saída e o seed
Defina output_format quando o tipo de arquivo importar mais adiante, porque converter depois custa uma nova codificação: PNG para um arquivo sem perdas que você vai continuar editando, WebP para resultados que vão direto para a web, JPEG se você não disser nada. Nenhum dos três muda o preço, então escolha o que o seu fluxo precisa, não o que parece mais barato. Fixe um seed só quando quiser comparar execuções: duas execuções sobre o mesmo par recebem o mesmo sorteio, e a única coisa que se move é a variável que você mudou. É uma ferramenta de comparação, não a promessa de uma imagem idêntica byte a byte. Em produção, o normal é querer um sorteio novo a cada vez.
Quando o resultado não sai como você queria
| O que você vê | O que mudar primeiro |
|---|---|
| Uma emenda no queixo apesar do ajuste de tom | Use uma referência iluminada da mesma direção — o tom é ajustado, a direção não |
| A linha do cabelo mudou e você queria mantê-la | Esperado aqui; use Face Swap ou Face Swap Pro |
| A instrução não teve efeito visível | Esperado — o campo não age aqui; mude a imagem de destino |
| A pessoa errada mudou | Recorte o destino até ficar uma pessoa só |
| Traços moles ou aproximados | Use uma referência com o rosto maior e mais nítido |
Escolher o endpoint certo
| O que você precisa | Endpoint |
|---|---|
| Ajuste de tom de pele e escolha do formato de arquivo | Este endpoint |
| Precisão nos pontos do rosto e textura original, sem ajustes | Face Swap Pro |
| A troca simples com seed, sem nunca mexer no cabelo | Face Swap |
| A cabeça inteira, com cabelo, sempre | Head Swap |
| Um rosto ao longo de um clipe em movimento | Video Face Swap |
Rodar em lote
Dois campos obrigatórios e três valores padrão fazem de 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-v1-plus/edit",
"input": {
"image_url": "https://example.com/reference.png",
"output_format": "jpeg",
"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.
