API de face swap: como adicionar troca de rosto ao seu app

Uma API de face swap permite que o seu app coloque o rosto de uma pessoa em outra foto com uma única requisição HTTP. Este guia mostra a requisição em curl, JavaScript e Python, como lidar com tarefas longas e fotos em grupo, o que os erros significam, quanto custa e como usar de forma responsável.

Equipe Morfran · 5 min de leitura · atualizado em 22 nov 2026

O que uma API de troca de rosto faz

Uma API de face swap recebe duas imagens e devolve uma nova. A imagem de origem mostra o rosto que você quer usar. A imagem de destino é a foto que você quer alterar. A API encontra o rosto no destino, substitui pelo rosto da origem e ajusta tom de pele, luz e ângulo para que o resultado pareça uma única foto.

Desenvolvedores usam isso para coisas como cartões personalizados, campanhas do tipo "coloque você no pôster", ferramentas de avatar e perfil, personagens de jogos e apps de cabine de fotos em eventos. Em vez de treinar e hospedar seus próprios modelos, você envia uma requisição HTTP e recebe uma imagem.

Antes de começar

Você precisa de três coisas:

  1. Uma conta Morfran. Contas novas recebem 50 créditos grátis, o suficiente para dez trocas de rosto individuais.
  2. Uma chave de API. Crie uma no seu painel, em Chaves de API. Mantenha-a no seu servidor e nunca a coloque no código do navegador ou de um app mobile.
  3. Duas URLs públicas de imagem. JPG, PNG ou WebP. A origem deve mostrar um rosto nítido, olhando mais ou menos para a câmera.

Toda requisição envia a chave no cabeçalho X-API-Key. A URL base é https://api.morfran.com.

Sua primeira troca de rosto com curl

curl -X POST https://api.morfran.com/v1/face-swap \
  -H "X-API-Key: $MORFRAN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"SourceImageUrl":"https://example.com/face.jpg","TargetImageUrl":"https://example.com/photo.jpg"}'

Por padrão, a chamada é síncrona: a API espera o resultado (até cerca de 60 segundos) e devolve uma resposta JSON com um link para a imagem pronta em cdn.morfran.com, além dos créditos usados. Baixe a imagem logo, porque os resultados são apagados depois de uma hora.

A mesma requisição em JavaScript (Node.js)

const res = await fetch("https://api.morfran.com/v1/face-swap", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.MORFRAN_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    SourceImageUrl: "https://example.com/face.jpg",
    TargetImageUrl: "https://example.com/photo.jpg",
  }),
});
const data = await res.json();
console.log(res.status, data);

Rode isso no seu servidor, não no navegador, para que sua chave continue privada.

A mesma requisição em Python

import os
import requests

res = requests.post(
    "https://api.morfran.com/v1/face-swap",
    headers={"X-API-Key": os.environ["MORFRAN_KEY"]},
    json={
        "SourceImageUrl": "https://example.com/face.jpg",
        "TargetImageUrl": "https://example.com/photo.jpg",
    },
    timeout=90,
)
print(res.status_code, res.json())

Tarefas longas: use o modo assíncrono

Se o seu app não deve ficar esperando com uma requisição aberta, adicione ?async=true à URL. A API responde na hora com um id de tarefa. Depois, leia o resultado com GET /v1/face-swap/{taskId} a cada poucos segundos até ele ficar pronto. Isso funciona bem atrás de uma fila de tarefas, ou quando o seu próprio servidor tem um timeout de requisição curto.

Fotos em grupo: troque até oito rostos

Para uma foto de equipe ou de família, use POST /v1/face-swap/group. Ele troca até oito rostos em uma única chamada; MaxFaces define o limite. Uma troca em grupo custa 10 créditos e uma troca individual, 5 créditos. A lista completa de campos está na documentação da API e no esquema OpenAPI.

Trate erros e créditos

  • 401: a chave de API está ausente ou incorreta. Confira o cabeçalho X-API-Key.
  • 402: créditos insuficientes. Compre um pacote de créditos no seu painel.
  • 422: nenhum rosto foi encontrado. Peça ao usuário uma foto mais nítida com um único rosto.

Requisições com falha não são cobradas. Os créditos só são descontados por imagens prontas, então tentar de novo depois de um 422 não custa duas vezes. Você pode consultar seu saldo a qualquer momento com GET /v1/credits/balance, que é grátis.

Dicas para resultados melhores

  • Use um rosto de origem nítido. Uma pessoa, de frente para a câmera, olhos abertos, sem óculos escuros, boa luz.
  • Combine o ângulo. Um rosto olhando para a frente se encaixa melhor em um destino em que a pessoa também olha mais ou menos para a câmera.
  • Mantenha os rostos grandes o suficiente. Um rosto com poucos pixels de largura no destino não pode ser bem trocado.
  • Luz parecida ajuda. Um rosto fotografado com luz do dia fica mais natural em uma foto de destino com luz do dia.
  • Teste com suas imagens reais. Gaste alguns dos créditos grátis em fotos parecidas com as que seus usuários vão enviar.

Consentimento e privacidade

Só troque o rosto de alguém que tenha concordado com isso. Não use a troca de rosto para enganar pessoas, se passar por alguém ou criar conteúdo que prejudique uma pessoa real. Se publicar resultados, identifique-os como gerados por IA. Imagens enviadas e resultados são apagados do nosso armazenamento em até uma hora, e não os usamos para treinar modelos de IA. Uso indevido pode ser denunciado pela página de contato e é tratado em até 48 horas.

Use a partir de um agente de IA

A mesma troca de rosto está disponível no servidor MCP da Morfran em https://api.morfran.com/mcp, para que assistentes como o Claude possam chamá-la com a sua chave de API. A configuração está descrita na seção MCP da documentação.

Perguntas

Quanto custa a API de troca de rosto?

Uma troca de rosto individual custa 5 créditos e uma troca em grupo (até oito rostos) custa 10 créditos. Contas novas recebem 50 créditos grátis. Depois disso, você compra pacotes de créditos; não há assinatura. Veja os pacotes em preços.

Quanto tempo leva uma troca de rosto?

A maioria dos resultados volta dentro da espera síncrona de cerca de 60 segundos. Para tarefas longas ou timeouts curtos no servidor, use ?async=true e leia o resultado com o id da tarefa.

Posso enviar imagens em base64 em vez de URLs?

Os exemplos aqui usam URLs públicas, que é o jeito mais simples. O esquema OpenAPI lista todos os campos de entrada que o endpoint aceita.

Por quanto tempo os resultados ficam armazenados?

Imagens enviadas e resultados são apagados em até uma hora. Salve a imagem do resultado do seu lado assim que recebê-la.

Posso testar sem escrever código?

Sim. Entre na sua conta e abra o Playground. Ele executa a mesma troca de rosto no navegador e mostra a requisição de API correspondente.