Limite de evidência
Uma referência de contrato público, não um diagrama de infraestrutura privada
Use-a para decidir onde propriedade, validação, estado da tarefa, repetição, liquidação, entrega, exclusão e evidência devem residir em sua própria integração. Para campos e respostas exatos de multipart, use o Documentação API e contrato OpenAPI 3.1. Para os conceitos de pesquisa dentro de localização facial, transferência de identidade, síntese, mesclagem e consistência de vídeo, leia como funciona a troca de rosto por IA.
Contrato público verificado
Cinco workflows assíncronos compartilham uma forma de controle
Todo workflow de geração atual autentica com uma chave Bearer API, aceita mídia multipart, retorna um taskIde expõe status com escopo do proprietário através de GET na mesma rota. A conclusão usa polling; callbacks de webhook e SDKs oficiais de linguagem não estão publicados atualmente.
| Fluxo de trabalho | POST e GET de polling | Unidade de custo | Limite primário |
|---|---|---|---|
| Foto | /api/ai-tasks | 6 créditos por tarefa | 30 MB por imagem |
| Foto em lote | /api/ai-tasks/batch-face-swap | 6 créditos por saída | 20 imagens, 95 MB combinados |
| Foto em grupo mapeada | /api/ai-tasks/multi-face-swap | 6 créditos por rosto de substituição | 10 rostos mapeados, 95 MB combinados |
| Vídeo | /api/ai-tasks/video | Somente rosto com preservação de cena: 3/s, mínimo 12 em 1080p | 600 segundos, 95 MB de upload combinado |
| GIF / clipe curto | /api/ai-tasks/gif | 3 crédito por segundo, mínimo 12 | 30 segundos, 95 MB de destino |
O espaço de trabalho ao vivo e a documentação da API continuam sendo a referência para formatos exatos, cobranças mínimas e campos de solicitação. Tarefas de conta e de API exigem um e-mail verificado, apenas uma geração pode ficar ativa por conta e limites esgotados podem retornar HTTP 429 com informações para nova tentativa.
Arquitetura de referência
Dê a cada decisão irreversível um proprietário
Ingresso e identidade
Finalize TLS, autentique a chave mantida no servidor, atribua um ID de correlação de requisição e vincule cada tarefa a uma conta.
Política e validação
Verifique estado de permissão, campos do workflow, tipo de mídia detectado, tamanho em bytes, contagem, duração, mapeamento, prontidão da conta e disponibilidade de crédito.
Registro de tarefa
Persista o taskId, proprietário, workflow, cobrança esperada, transições de estado, timestamps e resultado da liquidação antes de retornar o controle.
Processamento limitado
Desacople a aceitação da requisição da geração, limite o trabalho ativo e distinga falhas de transporte repetíveis de entradas inválidas.
Liquidação
Use uma autoridade atômica para decisões de reserva, conclusão e reembolso de tarefas com falha, para que uma repetição não possa cobrar ou reembolsar duas vezes.
Entrega e exclusão
Autorize o acesso ao resultado pelo proprietário da tarefa, aplique a permissão de exportação de imagem e remova a mídia no cronograma documentado de 24 horas.
Sequência de requisição de oito etapas
Da requisição de contrato à exclusão com respaldo de evidência
- Congele o contrato público de requisição. Escolha o workflow exato e registre campos, limites de mídia, unidade de custo e estados terminais.
- Controle autorização, consentimento e prontidão da conta. Mantenha a chave API no lado do servidor e exija uma decisão de permissão antes de aceitar mídia.
- Valide a mídia e calcule o custo antes de enfileirar. Inspecione tipo detectado, tamanho, contagem, duração, mapeamento e créditos disponíveis antes do trabalho caro.
- Crie um registro de tarefa durável. Persista propriedade, workflow, cobrança esperada, referências de entrada, estado e taskId.
- Processe de forma assíncrona atrás de uma fila limitada. Limite a concorrência e classifique falhas transitórias versus permanentes.
- Liquide créditos exatamente uma vez. Comprometa o trabalho concluído e aplique o caminho de reembolso de processamento com falha documentado sem liquidação dupla.
- Exponha status com escopo do proprietário e acesso ao resultado. Faça polling em um intervalo medido e pare em COMPLETED, FAILED ou CANCELLED.
- Force a exclusão e retenha evidências operacionais. Remova a mídia no cronograma, retendo apenas o mínimo permitido de registro de tarefa, cobrança, segurança e suporte.
Estado e liquidação
Mantenha o estado de processamento separado do estado financeiro
| Evento | Registro de tarefa | Ação de crédito | Ação do cliente |
|---|---|---|---|
| Requisição rejeitada antes da criação da tarefa | Nenhuma tarefa aceita | Não infira uma cobrança | Corrija a requisição ou o estado da conta |
| Tarefa aceita | Persista taskId e custo esperado | Trate a liquidação como de propriedade do servidor | Inicie polling medido |
| Tarefa concluída | Resultado terminal | Trabalho concluído permanece liquidado | Autorize recuperação do resultado |
| Falha no processamento | Falha terminal | Contrato atual reembolsa processamento com falha automaticamente | Leia a falha antes de decidir reenviar |
| Resultado da resposta incerto | Reconcilie antes de outro POST | Nunca adivinhe a partir de um timeout | Use o taskId armazenado ou o histórico da conta |
Nenhum campo idempotency-key está documentado no contrato público. O serviço de chamada deve desabilitar submissão duplicada, persistir o primeiro taskId e reconciliar uma resposta de rede incerta antes de emitir outro POST.
Política de falha
Repita apenas quando a classe de falha permitir
| Status | Classe de falha | Resposta da arquitetura |
|---|---|---|
| 400 | Requisição ou mídia inválida | Rejeite permanentemente até que campos ou mídia mudem. |
| 401 / 403 | Prontidão da chave ou conta | Gire a chave ou complete a verificação; não faça loop. |
| 402 | Créditos insuficientes | Adicione créditos e envie uma nova tarefa somente após confirmação. |
| 404 | Proprietário, rota ou taskId incorretos | Concilie a identidade e os metadados da tarefa armazenados. |
| 429 | Limite de taxa ou geração ativa | Respeite o Retry-After quando fornecido, adicione jitter e limite as tentativas. |
| 500 | Falha de aceitação ou leitura temporária | Use backoff exponencial limitado e reconcilie antes do envio duplicado. |
Observabilidade e segurança
Rastreie decisões de controle sem copiar mídia confidencial para logs
A telemetria de tarefa recomendada inclui um ID de correlação, taskId, identificador da conta, fluxo de trabalho, fatos de mídia sanitizados, valor de crédito esperado, transições de estado, contagem de tentativas, classe de erro, evento de liquidação e timestamp de exclusão. Não registre chaves API, imagens faciais, nomes de arquivo completos enviados, URLs de resultados assinados ou corpos multipartes. A Recomendação de Contexto de Rastreamento W3C define contexto de solicitação interoperável; é uma opção de design, não uma afirmação sobre a implementação privada da DeepSwapAI.
Para defesas de upload, valide nomes de arquivo decodificados, conteúdo detectado, formatos permitidos, contagens e tamanhos; não confie apenas no Content-Type fornecido pelo navegador. O OWASP File Upload Cheat Sheet é a referência de segurança externa. Use o planejador de consentimento e divulgação para o portal de autorização humana e o Centro de Confiança para os limites atuais do serviço público.
Custo total de propriedade
Compare gerenciado, auto-hospedado e híbrido na mesma carga de trabalho medida
Não compare um encargo API com aluguel de GPU bruto isoladamente. Fixe primeiro uma janela de carga de trabalho: mix de fluxo de trabalho, duração e resolução da mídia, concorrência de pico, taxa de repetição, retenção, volume de revisão e disponibilidade necessária. Em seguida, atribua todo custo recorrente e relacionado a falhas à mesma janela.
| Dimensão de custo | API Gerenciado | Auto-hospedado | Híbrido | Evidência a coletar |
|---|---|---|---|---|
| Capacidade de processamento | Taxa por tarefa ou duração publicada | Aluguel ou compra de GPU, capacidade ociosa, escalonamento e tempo de execução do modelo | Linha de base interna mais estouro externo ou processamento especializado | Unidades concluídas, duração, resolução, concorrência e utilização |
| Engenharia e operações | Integração, persistência de tarefas, polling, revisão e tratamento de mudanças de fornecedor | Servir modelo, fila, atualizações, planejamento de capacidade, implantação e resposta em plantão | Orquestração, abstração de provedor e propriedade da plataforma interna | Horas de engenharia medidas, cadência de lançamento e carga de plantão |
| Segurança e governança | Portal de consentimento da aplicação, política da conta, revisão e evidência | Todos os controles de moderação, armazenamento, exclusão, controle de acesso e auditoria | Controles compartilhados com um proprietário explícito para cada decisão | Minutos de revisão, taxa de escalonamento, escopo de retenção e proprietários de controle |
| Armazenamento e entrega | Manipulação de entrada, resultado e rede no lado da aplicação | Operações de entrada, intermediário, resultado, backup, saída e exclusão | Registros internos mais transferências limitadas do provedor | Bytes retidos, volume de transferência, tempo de retenção e trabalho de exclusão |
| Falha e confiabilidade | Repetição, reconciliação, tratamento de falha do provedor e custo de troca | Redundância, resposta a incidentes, tarefas com falha, recuperação e capacidade não utilizada | Falha de dependência e falha de orquestração interna | Taxa de falha, tempo de recuperação, trabalho duplicado e carga de suporte |
Este framework não publica nenhum benchmark de preço auto-hospedado e não afirma que gerenciado, auto-hospedado ou híbrido é universalmente mais barato. A decisão depende da carga de trabalho e dos controles que podem ser evidenciados para o mesmo período.
Decisão de construção
Escolha gerenciado, auto-hospedado ou híbrido pelos controles que você deve possuir
| Modelo | Você possui | Dependência externa | Melhor ajuste |
|---|---|---|---|
| API Gerenciado | Portal de consentimento, UX da aplicação, persistência de tarefas, polling, revisão e política de negócios | API publicado, limites, preços e comportamento de processamento | Equipes que priorizam velocidade de integração sobre controle de infraestrutura |
| Auto-hospedado | Modelo, capacidade de GPU, fila, moderação, armazenamento, segurança, liquidação, exclusão e resposta a incidentes | Cadeia de suprimentos de modelo e infraestrutura | Equipes com um requisito de controle ou implantação justificado e capacidade operacional |
| Híbrido | Política interna, orquestração, registro de auditoria, revisão e abstração de provedor | Um ou mais serviços de geração limitados | Equipes que precisam de controle no nível da aplicação sem operar cada componente do modelo |
Fontes e método
Fatos atuais do produto mais padrões externos primários
A Equipe de Produto DeepSwapAI verificou as cinco rotas públicas, autenticação Bearer, solicitações multipartes, estados de tarefa, fluxo de polling, respostas de erro, limite de concorrência, liquidação de crédito, direito a imagem de teste e exclusão de mídia em 24 horas em 22 de julho de 2026. Os controles recomendados são informados pelo Especificação OpenAPI 3.1.2, guia de upload OWASP, NIST AI RMF 1.0, e W3C Trace Context. Consulte a metodologia de verificação de reivindicações para saber como as declarações atuais do produto são separadas da orientação geral de design.
Perguntas de arquitetura
Saiba o que o contrato público estabelece e não estabelece
Esta é a arquitetura de produção privada do DeepSwapAI?
Não. É uma referência de design de contrato público e não divulga topologia do provedor, tecnologia de fila, posicionamento do modelo, número de workers, rede interna ou metas de nível de serviço.
Como um cliente sabe que uma tarefa foi concluída?
Mantenha o taskId retornado pelo POST e faça polling GET na mesma rota de fluxo de trabalho até COMPLETED, FAILED ou CANCELLED. Callbacks de webhook não são publicados atualmente.
A chave API pode ser colocada no código do cliente?
Não. Trate-a como um segredo do lado do servidor e mantenha-a fora de bundles de navegador, binários móveis, repositórios, análises, logs e mensagens de suporte.
O API publica uma chave de idempotência?
Nenhum campo de chave de idempotência está documentado. Evite envio duplicado, persista o primeiro taskId e reconcilie respostas incertas antes de outro POST.
Este design garante taxa de transferência ou qualidade?
Não. Não é um benchmark, SLA, pontuação de precisão ou garantia de qualidade.