API para desenvolvedores · v1

API de troca de rosto para imagens, vídeos, GIFs e fotos em grupo

Use o mesmo pipeline de tarefas de produção que os web studios FaceSwapAI por meio de rotas com versão estável. Autenticação, fórmulas de crédito reais, limites de arquivos, estados de tarefas e comportamento de falha são documentados nos manipuladores em execução.

Contrato de produção ao vivo · OpenAPI 3.1 · Atualizado em 30 de agosto de 2026

Início rápido

Crie uma chave em sua conta verificada, envie uma solicitação multiparte de seu servidor e, em seguida, pesquise a rota GET correspondente com o taskId retornado. Mantenha o segredo fora dos pacotes de navegadores e clientes móveis.

  1. 1Crie e copie uma chave uma vez
  2. 2Enviar mídia local com consentimento=true
  3. 3Consulte enquanto o status for PENDING ou PROCESSING
cURL
curl --request POST https://faceswapai.com/api/v1/face-swap/image \
  --header "Authorization: Bearer $FACESWAPAI_API_KEY" \
  --form "sourceImage=@./source.jpg" \
  --form "targetImage=@./target.jpg" \
  --form "consent=true"

Endpoints e preços exatos

MétodoRotaFinalidadeFórmula de crédito
POST/api/v1/face-swap/imageTroca de rosto de imagem6
POST/api/v1/face-swap/videoTroca de rosto de vídeomax(9, 3 × ceil(serverMeasuredInputSeconds))
POST/api/v1/face-swap/gifGIF troca de rostomax(9, 3 × ceil(serverMeasuredInputSeconds))
POST/api/v1/face-swap/multipleTroca de imagens de múltiplas faces6 × selectedTargetFaces
GET/api/v1/tasksHistórico de tarefas0

Exemplos de crédito trabalhados

Uma tarefa de imagem66 créditos
Vídeo de quatro segundosmax(9, 3 × ceil(4))12 créditos
GIF de oito segundosmax(9, 3 × ceil(8))24 créditos
GIF de dezoito segundosmax(9, 3 × ceil(18))54 créditos

Campos de solicitação por endpoint

Escolha a rota por mídia de destino e envie os campos multipart exatos abaixo. Os controles de restauração opcionais aceitam números de 0 a 1.

POST/api/v1/face-swap/image

Troca de rosto de imagem

Aplique uma identidade de origem a uma foto de destino.

Obrigatório
sourceImagetargetImageconsent=true
Opcional
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/video

Troca de rosto de vídeo

Aplique uma identidade de origem em todo um vídeo de destino enviado.

Obrigatório
sourceImagetargetVideoconsent=true
Opcional
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/gif

GIF troca de rosto

Aplique uma identidade de origem em um destino GIF carregado.

Obrigatório
sourceImagetargetGifconsent=true
Opcional
faceRestoreVisibilityrestoreVisibility
POST/api/v1/face-swap/multiple

Troca de imagens de múltiplas faces

Substitua de um a dez rostos selecionados em uma foto de grupo.

Obrigatório
sourceImagetargetFace0consent=true
Opcional
targetFace1...targetFace9faceBox0...faceBox9
GET/api/v1/tasks

Histórico de tarefas

Lista tarefas pertencentes à conta autenticada.

Opcional
pagepageSizestatustaskType

Pesquise todas as tarefas de mídia

Depois que um POST de mídia retornar taskId, envie GET à mesma rota com taskId como parâmetro de consulta enquanto o status for PENDING ou PROCESSING. COMPLETED, FAILED e CANCELLED são terminais.

Autenticação do portador

Envie a chave em cada solicitação como Autorização: Portador YOUR_API_KEY. As chaves API herdam a conta verificada e seu saldo de crédito ativo. O limite autenticado no nível do aplicativo é de 300 solicitações por minuto; a capacidade de geração permanece dependente da fila.

HTTP
Authorization: Bearer YOUR_API_KEY

Exemplos de JavaScript e Python

Esses exemplos do lado do servidor enviam dois arquivos locais, rejeitam falhas de HTTP, pesquisam a rota da tarefa correspondente e imprimem o URL de resultado temporário. Cada campo vem do contrato OpenAPI ativo.

JavaScriptNode.js 18+
JavaScript · Node.js 18+
import { readFile } from 'node:fs/promises';

const apiUrl = 'https://faceswapai.com/api/v1/face-swap/image';
const headers = {
  Authorization: 'Bearer ' + process.env.FACESWAPAI_API_KEY,
};
const form = new FormData();
form.set('sourceImage', new Blob([await readFile('./source.jpg')]), 'source.jpg');
form.set('targetImage', new Blob([await readFile('./target.jpg')]), 'target.jpg');
form.set('consent', 'true');

const submitted = await fetch(apiUrl, { method: 'POST', headers, body: form });
if (!submitted.ok) throw new Error(submitted.status + ': ' + await submitted.text());
const { taskId } = await submitted.json();

let task;
do {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const polled = await fetch(apiUrl + '?taskId=' + encodeURIComponent(taskId), { headers });
  if (!polled.ok) throw new Error(polled.status + ': ' + await polled.text());
  task = await polled.json();
} while (task.status === 'PENDING' || task.status === 'PROCESSING');

console.log(task.status === 'COMPLETED' ? task.result?.url : task.result?.error);
Pythonrequests 2.x
Python · requests 2.x
import os
import time
import requests

api_url = "https://faceswapai.com/api/v1/face-swap/image"
headers = {"Authorization": "Bearer " + os.environ["FACESWAPAI_API_KEY"]}

with open("source.jpg", "rb") as source, open("target.jpg", "rb") as target:
    response = requests.post(
        api_url,
        headers=headers,
        files={"sourceImage": source, "targetImage": target},
        data={"consent": "true"},
        timeout=60,
    )
response.raise_for_status()
task_id = response.json()["taskId"]

while True:
    time.sleep(2)
    response = requests.get(api_url, headers=headers, params={"taskId": task_id}, timeout=30)
    response.raise_for_status()
    task = response.json()
    if task["status"] not in ("PENDING", "PROCESSING"):
        break

result = task.get("result") or {}
print(result.get("url") if task["status"] == "COMPLETED" else result.get("error"))

Envie e depois enquete

Um POST bem-sucedido reserva os créditos necessários e retorna taskId. Consulte a mesma rota de mídia enquanto o status for PENDING ou PROCESSING. COMPLETED, FAILED e CANCELLED são terminais. Uma falha na fila ou no provedor reembolsa a reserva pendente exatamente uma vez.

cURL
curl --get https://faceswapai.com/api/v1/face-swap/image \
  --header "Authorization: Bearer $FACESWAPAI_API_KEY" \
  --data-urlencode "taskId=YOUR_TASK_ID"
PENDING
Aceito e na fila
PROCESSING
Em execução
COMPLETED
O resultado está disponível
FAILED
Parado com um erro público
CANCELLED
Cancelado

Formatos e limites

As imagens aceitam JPG, PNG, WebP, GIF, BMP, HEIC ou HEIF de até 30 MB. O vídeo aceita MP4, MOV, WebM ou AVI de até 100 MB e 600 segundos. 100 MB equivalem a cerca de 1–2 minutos de um vídeo 1080p típico de celular, então comprima ou corte clipes mais longos. Os destinos GIF são limitados a 30 MB e 30 segundos. As entradas de múltiplas faces são limitadas a 15 MB cada e dez faces selecionadas.

Erros e novas tentativas de HTTP

Não tente novamente 400, 401, 402, 403 ou 413 respostas sem alterar a solicitação ou o estado da conta. Recue em 429. Um 500 ou 503 pode ser tentado novamente após um atraso; as reservas de crédito são protegidas pelo caminho de reembolso da tarefa.

Limites atuais de produção

Plano contra o contrato público v1 que existe hoje, incluindo o que ele não reivindica.

  • As tarefas de mídia são assíncronas e usam polling. O contrato público v1 atual não expõe um webhook.
  • Não há rota de lote pública, campo de chave de idempotência, rota de câmera ao vivo, SLA publicado ou tempo de conclusão garantido.
  • As chaves API pertencem a um servidor protegido. Os resultados são temporários, a capacidade de geração depende da fila e as falhas aceitas utilizam o caminho de reembolso documentado.

Consentimento, privacidade e marca d'água

Cada geração requer consent=true, o que significa que você tem permissão para usar todos os rostos enviados. A mídia da tarefa é temporária. Não há teste grátis: cada tarefa é paga com créditos de compra única, e nenhum resultado contém marca d'água nem o e-mail da conta.

Perguntas frequentes sobre troca de rosto API

Existe uma chave Face Swap API gratuita?

A criação de uma chave API é gratuita. A geração utiliza o saldo de créditos da conta. Não há teste grátis nem nível API gratuito: cada tarefa é paga com créditos de compra única, a partir de 600 créditos por US$ 19,99.

O API suporta vídeo e múltiplos rostos?

Sim. As rotas versionadas abrangem tarefas de imagem, vídeo, GIF e imagens de múltiplas faces. Os preços de vídeo e GIF são calculados a partir de metadados de mídia medidos.

Como posso saber quando um resultado está pronto?

Leia taskId da resposta POST e consulte a rota GET correspondente enquanto o status for PENDING ou PROCESSING. COMPLETED inclui a URL temporária do resultado; FAILED e CANCELLED também são terminais.

Posso ligar para API diretamente de um navegador?

Não exponha uma chave secreta no código do navegador. Envie solicitações do seu próprio servidor, função sem servidor ou outro back-end protegido.