Limite de evidência
Uma referência de contrato público, não um diagrama de infraestrutura privada
Use-a para decidir onde a propriedade, validação, estado da tarefa, repetição, liquidação, entrega, eliminação e evidência devem residir na sua própria integração. Para campos e respostas exatos de várias partes, use o Documentação API e contrato OpenAPI 3.1. Para os conceitos de investigação dentro da localização facial, transferência de identidade, síntese, mistura e consistência de vídeo, leia como funciona a troca de rosto por IA.
Contrato público verificado
Cinco fluxos de trabalho assíncronos partilham uma forma de controlo
Cada fluxo de trabalho de geração atual autentica com uma chave Bearer API, aceita média de várias partes, devolve um taskId, e expõe estado com âmbito do proprietário através de GET na mesma rota. A conclusão usa polling; callbacks de webhook e SDKs de linguagem oficiais não estão atualmente publicados.
| Fluxo de trabalho | POST e GET de polling | Unidade de custo | Limite primário |
|---|---|---|---|
| Foto | /api/ai-tasks | 3 créditos por tarefa | 30 MB por imagem |
| Lote de fotos | /api/ai-tasks/batch-face-swap | 3 créditos por saída | 20 imagens, 95 MB combinados |
| Foto de grupo mapeada | /api/ai-tasks/multi-face-swap | 3 créditos por rosto de substituição | 10 rostos mapeados, 95 MB combinados |
| Vídeo | /api/ai-tasks/video | Apenas rosto com preservação de cena: 1/s, mínimo 5 no 1080p | 600 segundos, 95 MB de upload combinado |
| GIF / clipe curto | /api/ai-tasks/gif | 1 crédito por segundo, mínimo 5 | 30 segundos, 95 MB alvo |
O espaço de trabalho ativo e a documentação API permanecem autoritativos para formatos exatos, cobranças mínimas e campos de pedido. Um e-mail de conta verificado é necessário, uma geração pode estar ativa por conta, e limites esgotados podem devolver HTTP 429 com informações de repetição.
Arquitetura de referência
Dar a cada decisão irreversível um proprietário
Ingresso e identidade
Terminar TLS, autenticar a chave detida pelo servidor, atribuir um ID de correlação de pedido e vincular cada tarefa a uma conta.
Política e validação
Verificar estado de permissão, campos do fluxo de trabalho, tipo de média detetado, tamanho em bytes, contagem, duração, mapeamento, prontidão da conta e disponibilidade de crédito.
Registo de tarefas
Persistir o taskId, proprietário, fluxo de trabalho, cobrança esperada, transições de estado, carimbos de data/hora e resultado da liquidação antes de devolver o controlo.
Processamento limitado
Desacoplar a aceitação do pedido da geração, limitar o trabalho ativo e distinguir falhas de transporte repetíveis de entradas inválidas.
Liquidação
Usar uma autoridade atómica para decisões de reserva, conclusão e reembolso de tarefa falhada para que uma repetição não possa cobrar ou reembolsar duas vezes.
Entrega e eliminação
Autorizar acesso ao resultado pelo proprietário da tarefa, aplicar a permissão de exportação de imagem e eliminar média no cronograma documentado de 24 horas.
Sequência de pedido de oito passos
Desde o contrato de pedido até à eliminação apoiada por evidências
- Congelar o contrato público de pedido. Escolher o fluxo de trabalho exato e registar campos, limites de média, unidade de custo e estados terminais.
- Controlar autorização, consentimento e prontidão da conta. Manter a chave API no lado do servidor e exigir uma decisão de permissão antes de aceitar média.
- Validar média e calcular custo antes de enfileirar. Inspecionar tipo detetado, tamanho, contagem, duração, mapeamento e créditos disponíveis antes de trabalho dispendioso.
- Criar um registo de tarefa durável. Persistir propriedade, fluxo de trabalho, cobrança esperada, referências de entrada, estado e taskId.
- Processar assincronamente atrás de uma fila limitada. Limitar concorrência e classificar falhas transitórias versus permanentes.
- Liquidar créditos exatamente uma vez. Comprometer trabalho concluído e aplicar o caminho de reembolso de processamento falhado documentado sem liquidação dupla.
- Expor estado com âmbito do proprietário e acesso ao resultado. Fazer polling a um intervalo medido e parar em COMPLETED, FAILED ou CANCELLED.
- Impor eliminação e reter evidências operacionais. Eliminar média no cronograma enquanto retém apenas o mínimo permitido de registo de tarefa, faturação, segurança e suporte.
Estado e liquidação
Manter estado de processamento separado do estado monetário
| Evento | Registo de tarefa | Ação de crédito | Ação de cliente |
|---|---|---|---|
| Pedido rejeitado antes da criação da tarefa | Nenhuma tarefa aceite | Não inferir uma cobrança | Corrigir o pedido ou estado da conta |
| Tarefa aceite | Persistir taskId e custo esperado | Tratar liquidação como propriedade do servidor | Iniciar sondagem medida |
| Tarefa concluída | Resultado terminal | Trabalho concluído permanece liquidado | Autorizar recuperação de resultado |
| Processamento falhou | Falha terminal | O contrato atual reembolsa automaticamente processamento falhado | Ler a falha antes de decidir reenviar |
| Resultado da resposta incerto | Conciliar antes de outro POST | Nunca adivinhar a partir de um timeout | Usar o taskId armazenado ou histórico da conta |
Nenhum campo idempotency-key está documentado no contrato público. O serviço chamador deve desativar submissão duplicada, persistir o primeiro taskId e conciliar uma resposta de rede incerta antes de emitir outro POST.
Política de falha
Repetir apenas quando a classe de falha o permitir
| Estado | Classe de falha | Resposta da arquitetura |
|---|---|---|
| 400 | Pedido ou média inválidos | Rejeitar permanentemente até que campos ou média mudem. |
| 401 / 403 | Chave ou prontidão da conta | Rodar a chave ou concluir verificação; não repetir em ciclo. |
| 402 | Créditos insuficientes | Adicionar créditos e submeter uma nova tarefa apenas após confirmação. |
| 404 | Proprietário, rota ou taskId errados | Conciliar identidade e metadados de tarefa armazenados. |
| 429 | Limite de taxa ou geração ativa | Respeitar Retry-After quando fornecido, adicionar jitter e limitar repetições. |
| 500 | Aceitação temporária ou falha de leitura | Usar backoff exponencial limitado e conciliar antes de submissão duplicada. |
Observabilidade e segurança
Controlar decisões de rastreio sem copiar média sensível para registos
A telemetria de tarefa recomendada inclui um ID de correlação, taskId, identificador de conta, fluxo de trabalho, factos de média sanitizados, montante de crédito esperado, transições de estado, contagem de repetições, classe de erro, evento de liquidação e carimbo de data/hora de eliminação. Não registar chaves API, imagens faciais, nomes de ficheiros carregados completos, URLs de resultado assinados ou corpos multipart. A Recomendação de Contexto de Rastreio W3C define contexto de pedido interoperável; é uma opção de design, não uma afirmação sobre a implementação privada da DeepSwapAI.
Para defesas de carregamento, validar nomes de ficheiros descodificados, conteúdo detetado, formatos permitidos, contagens e tamanhos; não confiar apenas no Content-Type fornecido pelo navegador. A OWASP File Upload Cheat Sheet é a referência de segurança externa. Usar o planeador de consentimento e divulgação para a porta de autorização humana e o Centro de Confiança para os limites atuais do serviço público.
Custo total de propriedade
Comparar gerido, auto-hospedado e híbrido na mesma carga de trabalho medida
Não comparar uma cobrança API com aluguer de GPU bruto isoladamente. Fixar primeiro uma janela de carga de trabalho: mistura de fluxos de trabalho, duração e resolução de média, concorrência de pico, taxa de repetição, retenção, volume de revisão e disponibilidade necessária. Depois, atribuir cada custo recorrente e relacionado com falhas à mesma janela.
| Dimensão de custo | API Gerido | Auto-hospedado | Híbrido | Evidência a recolher |
|---|---|---|---|---|
| Capacidade de processamento | Cobrança por tarefa ou duração publicada | Aluguer ou compra de GPU, capacidade ociosa, escalabilidade e tempo de execução do modelo | Linha de base interna mais transbordo 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 tarefa, sondagem, revisão e tratamento de mudanças de fornecedor | Servir modelo, fila, atualizações, planeamento de capacidade, implantação e resposta em serviço | Orquestração, abstração de fornecedor e propriedade da plataforma interna | Horas de engenheiro medidas, cadência de lançamento e carga de serviço |
| Segurança e governação | Porta de consentimento da aplicação, política de conta, revisão e evidência | Todos os controlos de moderação, armazenamento, eliminação, controlo de acesso e auditoria | Controlos partilhados com um proprietário explícito para cada decisão | Minutos de revisão, taxa de escalada, âmbito de retenção e proprietários de controlo |
| Armazenamento e entrega | Manuseamento de entrada, resultado e rede do lado da aplicação | Operações de entrada, intermédio, resultado, backup, saída e eliminação | Registos internos mais transferências limitadas do fornecedor | Bytes retidos, volume de transferência, tempo de retenção e trabalho de eliminação |
| Falha e fiabilidade | Repetição, reconciliação, tratamento de falhas do fornecedor e custo de mudança | Redundância, resposta a incidentes, tarefas falhadas, 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 quadro não publica nenhum benchmark de preço auto-hospedado e não afirma que gerido, auto-hospedado ou híbrido é universalmente mais barato. A decisão depende da carga de trabalho e dos controlos que podem ser evidenciados para o mesmo período.
Decisão de construção
Escolher gerido, auto-hospedado ou híbrido pelos controlos que deve possuir
| Modelo | Você possui | Dependência externa | Melhor ajuste |
|---|---|---|---|
| API Gerido | Porta de consentimento, UX da aplicação, persistência de tarefa, sondagem, revisão e política de negócio | API publicado, limites, preços e comportamento de processamento | Equipas que priorizam velocidade de integração sobre controlo de infraestrutura |
| Auto-hospedado | Modelo, capacidade GPU, fila, moderação, armazenamento, segurança, liquidação, eliminação e resposta a incidentes | Modelo e cadeia de fornecimento de infraestrutura | Equipas com um requisito de controlo ou implantação justificado e capacidade operacional |
| Híbrido | Política interna, orquestração, registo de auditoria, revisão e abstração de fornecedor | Um ou mais serviços de geração limitados | Equipas que precisam de controlo ao nível da aplicação sem operar cada componente do modelo |
Fontes e método
Factos atuais do produto mais normas externas primárias
A Equipa de Produto DeepSwapAI verificou as cinco rotas públicas, autenticação Bearer, pedidos multipart, estados de tarefa, fluxo de sondagem, respostas de erro, limite de concorrência, liquidação de crédito, direito a imagem de teste e eliminação de média de 24 horas em 22 de julho de 2026. Os controlos recomendados são informados pela Especificação OpenAPI 3.1.2, orientação de carregamento OWASP, NIST AI RMF 1.0, e Contexto de Rastreio W3C. Ver a metodologia de verificação de reivindicações para como as declarações atuais do produto são separadas da orientação geral de design.
Perguntas de arquitetura
Saber 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 fornecedor, tecnologia de fila, colocação de modelo, contagem de trabalhadores, rede interna ou alvos de nível de serviço.
Como é que um cliente sabe que uma tarefa terminou?
Manter o taskId devolvido pelo POST e sondar GET na mesma rota de fluxo de trabalho até COMPLETED, FAILED ou CANCELLED. Callbacks de webhook não estão atualmente publicados.
A chave API pode ser colocada em código de cliente?
Não. Tratá-la como um segredo do lado do servidor e mantê-la fora de pacotes de navegador, binários móveis, repositórios, análises, registos e mensagens de suporte.
A API publica uma chave de idempotência?
Nenhum campo idempotency-key está documentado. Prevenir submissão duplicada, persistir o primeiro taskId e conciliar respostas incertas antes de outro POST.
Este design garante débito ou qualidade?
Não. Não é um benchmark, SLA, pontuação de precisão ou garantia de qualidade.