De duas APIs para um Smart API Router: regras, uma porta neural e Deep Analyze atrás de um único endpoint

Atualizado em 2026-10-17: marcado como post histórico, com remissão à arquitetura atual; removidos os limites das assinaturas e os números que já não valem.

Post histórico. Descreve o router como era em 2026-09-12: o modelo neural, o nível Deep Analyze e os limites das assinaturas dessa data. Desde 12 de outubro de 2026 a verificação na nuvem usa o Galvanize 2 (limiar 0,662), e os níveis do router são rules, advanced e deep. Para as assinaturas e limites atuais, veja preços.

Até esta semana, a zn oferecia duas APIs. Você escolhia uma por requisição, e os limites da sua assinatura ficavam divididos entre as duas. Era um imposto de design em cada integração: escolher errado dava uma falsa sensação de segurança, e escolher certo exigia entender nossas entranhas melhor do que você deveria precisar.

Hoje existe um único endpoint. POST /analyze encaminha cada requisição por três camadas progressivas — regras determinísticas, a porta neural e o Deep Analyze — e diz qual delas decidiu.

TL;DR

• POST /analyze agora é um Smart API Router (SAR): Nível 1 regras determinísticas (<50 µs), Nível 2 neural int8 (~15–18 ms), Nível 3 Deep Analyze (mmBERT v8, ~166 ms a quente) para a faixa ambígua.
• /v30/analyze continua como alias de compatibilidade. O caminho de produto POST /prod/analyze segue só-regras para quem quer a porta de latência ultrabaixa.
• O router é fail-open: se o Deep Analyze estourar o tempo (orçamento de 6 s) ou falhar, você ainda recebe o veredicto neural. Um gateway de segurança nunca deve ser a causa da queda.
• Os limites das assinaturas mudaram depois deste post. Os atuais estão na página de preços.
• Não guardamos o texto que envia em nenhum plano, a menos que ative o modo Contributor. Guardamos metadados de evidência, incluindo uma impressão digital SHA-256 da entrada, durante 90 dias. A resposta inclui tier, decided_by, latency_ms e um evidence_id auditável.

Por que duas APIs era o formato errado

O primeiro endpoint, POST /analyze, é um motor de regras determinísticas: normalização mais um catálogo de padrões de injeção (pi-direct e companhia). Responde em microssegundos, é trivialmente auditável e, quando uma regra dispara, quase nunca erra. Mas regras só pegam o que você já viu.

O segundo endpoint, POST /v30/analyze, roda uma porta neural: um transformer multilíngue, exportado para ONNX e quantizado em int8, que pontua o texto bruto e bloqueia acima de um limiar calibrado (τ = 0,950 após a passada de endurecimento multilíngue). A troca é outra: ~15–18 ms p50 em CPU, cobertura muito melhor, e ainda assim longe do custo e da latência de um guard baseado em LLM.

Os dois são produtos honestos. Juntos, eram uma interface ruim. Os clientes precisavam saber em qual modelo de ameaça estavam para escolher endpoint a cada chamada, as cotas eram separadas e as evidências dos dois caminhos não eram diretamente comparáveis. Na prática, as pessoas usavam o caminho rápido e perdiam em silêncio a cobertura neural que estavam pagando.

Um endpoint, três cérebros

O router decide por requisição, à vista de todos:

1. Nível 1 — Regras. Normaliza, casa padrões determinísticos. Se uma regra dispara, retorna. Custo: microssegundos.
2. Nível 2 — neural. Se as regras não concluem, pontua com o modelo int8. Casos claramente benignos ou claramente ataque terminam aqui.
3. Nível 3 — Deep Analyze. Só quando a pontuação neural cai na faixa incerta (0,50–0,935) a requisição vai para o Deep Analyze, o modelo mmBERT v8 que existe exatamente para isso: texto que parece benigno para um encoder pequeno mas merece uma segunda opinião.

A fusão do veredicto é simples de propósito: o router combina a pontuação neural com a do Deep Analyze e bloqueia a partir de 0,935. Cada resposta agora carrega tier (rules, advanced, deep), decided_by, latency_ms e evidence_id, para você medir seu próprio tráfego por caminho de decisão.

Deep Analyze: o nível que precisou merecer seu lugar

O Deep Analyze é nosso detector multilíngue mmBERT v8, exportado para ONNX int8 e servido numa Lambda de contêiner (3 GB de memória, 4 GB efêmeros, teto de 120 s). A quente responde em ~166 ms. Partidas a frio levam ~24 s, e é por isso que ele nunca fica na borda síncrona de um caminho desprotegido: só roda para a faixa ambígua, dentro de um orçamento duro de 6 s do router, e o router volta para o veredicto neural se estourar.

Conseguir um modelo bom o bastante para merecer essa vaga levou mais tempo que o próprio router. Nossos posts anteriores contaram a história completa: o dataset que mentia para nós e dezessete treinos fracassados em que o modelo pontuava 0,498–0,509 em tudo porque a perda nunca via um rótulo. A correção foi ordinária — treino supervisionado ponta a ponta, split congelado, parar de ajustar no teste — e o resultado foi uma porta funcional no split de teste congelado.

Implantar sem quebrar a produção

Um router na frente de cada requisição é um deploy assustador. Fizemos em três movimentos: primeiro o modo sombra, em que o caminho em produção e o router decidiam e só comparávamos — o Deep Analyze pontuando ao lado do veredicto de produção sem tocá-lo. Depois o canary em 50% atrás do alias, com alarmes do CloudWatch em erros de Lambda, fail-opens do Deep e latência p99, ligados ao SNS. Depois 100%.

As garantias chatas são o ponto: o rollback é trocar a versão do alias, o router tem 39/39 testes unitários incluindo uma suíte de equivalência que prova que o caminho roteado devolve o mesmo veredicto da chamada direta, e o caminho fail-open é exercitado em testes, não deixado à sorte.

Assinaturas

Os limites das assinaturas descritos quando este post foi publicado mudaram. Veja preços para as assinaturas e cotas atuais.

A retenção não muda: a entrada só é guardada no modo Contributor. Guardamos o veredicto, o nível e os hashes necessários para o Evidence Vault, com 90 dias de retenção. O modo Contributor é opcional e é o único caso em que a entrada é armazenada, anonimizada, e só porque você aceita a telemetria comunitária para treinar o modelo. Se você não ativar o modo Contributor, não usamos seus prompts para treinar. (Editado em 15 de outubro de 2026.)

O que muda para você

Se você chamava /v30/analyze, nada quebra: mesmo caminho, mesma forma de resposta, agora com tier e decided_by mostrando de onde veio cada veredicto. Se você chamava /analyze esperando só regras, migre para /prod/analyze para o caminho determinístico — ou fique, e ganhe o router completo pelo mesmo preço. Uma chave, um endpoint, três cérebros.

Se você quer ver o caminho de decisão no seu próprio tráfego antes de confiar nele, o plano Free (10.000 chamadas por mês) serve para isso: um POST, uma chave de API e evidência para cada bloqueio.

Atualizado em 14 de outubro de 2026: o texto sobre o tratamento de dados foi revisado para descrever o que o pacote e a API fazem hoje.