Quickstart da API

Passo 1

Crie uma chave no painel.

Crie uma conta pública, gere uma chave mmk_… e guarde o segredo como variável de ambiente. O segredo completo aparece uma única vez.

export ROTA_API_KEY="mmk_..."

Passo 2

Limpe um payload antes de qualquer destino.

Use /v1/privacy/clean para textos, JSON curto ou itens pequenos. A resposta traz cleaned, findings, contagens por categoria e audit_id, sem expor valores detectados.

curl https://rota-nacional.ia.br/v1/privacy/clean \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Paciente com CPF 452.198.736-28, CNS 898001160093761 e CRM-SP 123456.",
    "policy": "placeholder"
  }'

{
  "object": "privacy.clean",
  "action": "pseudonymized",
  "clean_text": "Paciente com CPF [CPF_1], [CNS_1] e [CRM_1].",
  "privacy": {
    "categories": ["cns", "cpf", "crm"],
    "counts": { "cns": 1, "cpf": 1, "crm": 1 },
    "total": 3
  },
  "audit_id": "aud_..."
}

Batch MVP

Envie lotes como jobs de privacidade.

O MVP processa o lote de forma síncrona e já retorna status: completed. O contrato está preparado para fila assíncrona e worker médico sem quebrar clientes.

curl https://rota-nacional.ia.br/v1/privacy/jobs \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "1", "text": "Prontuário ABC-123 com contato pessoa@example.invalid." },
      { "id": "2", "text": "Convênio SAUDE-4455 e consulta 09/07/2026." }
    ]
  }'

Depois consulte metadados do job, sem conteúdo bruto:

curl https://rota-nacional.ia.br/v1/privacy/jobs/privjob_... \
  -H "Authorization: Bearer $ROTA_API_KEY"

Áudio

Transcreva áudio e receba o texto já limpo.

Envie um arquivo de áudio (multipart, até 25 MB) para /v1/audio/transcriptions. A Rota transcreve, passa o texto pela mesma barreira de privacidade e devolve a transcrição já sanitizada, com privacy, findings e audit_id. O áudio bruto nunca é armazenado fora da auditoria cifrada. Contrato compatível com SDKs de transcrição OpenAI.

curl https://rota-nacional.ia.br/v1/audio/transcriptions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -F "file=@consulta.mp3" \
  -F "model=rota/transcricao" \
  -F "language=pt"

{
  "object": "audio.transcription",
  "text": "Paciente [PESSOA_1] no endereço [ENDERECO_1].",
  "privacy": { "categories": ["endereco", "nome"], "total": 2 },
  "audit_id": "aud_..."
}

Documentos

Extraia texto de PDF ou imagem — já limpo.

Envie um documento (multipart, até 25 MB) para /v1/privacy/extract. A Rota extrai o texto, aplica a barreira e devolve o resultado sanitizado com audit_id. PDF nato-digital tem extração determinística; imagem (PNG/JPEG/TIFF/WEBP) usa OCR marcado como beta — melhor-esforço, com notice na resposta. Documento ilegível falha com erro claro, sem devolver conteúdo bruto.

curl https://rota-nacional.ia.br/v1/privacy/extract \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -F "file=@encaminhamento.pdf"

{
  "object": "document.extraction",
  "source": "pdf",
  "pages": 2,
  "text": "Paciente com CPF [CPF_1] e [CNS_1].",
  "privacy": { "categories": ["cns", "cpf"], "total": 2 },
  "audit_id": "aud_..."
}

Inferência pela frota RN

Use uma API para texto, áudio, documentos e imagem.

A Rota escolhe o worker disponível; sua aplicação não recebe endereço de GPU nem precisa conhecer a topologia da frota. Consulte /v1/capabilities para descobrir o que os workers conectados podem executar naquele momento.

curl https://rota-nacional.ia.br/v1/capabilities \
  -H "Authorization: Bearer $ROTA_API_KEY"

/v1/chat/completions

Chat no worker com model: "rota/local". stream: true devolve SSE depois que o job termina; no MVP, o conteúdo chega em um único chunk.

/v1/embeddings

Vetores de texto pelo worker anunciado como rn.embeddings.

/v1/audio/speech

Síntese e clonagem de voz. Envie JSON com text, voz e motor opcionais.

/v1/audio/music

Geração de trilha por job assíncrono, com estilo, duração e seed controláveis.

/v1/audio/compositions

Mescla voz e fundo. Envie multipart com voice e background.

/v1/ocr

OCR local de imagem ou PDF, com resultado novamente tratado pela barreira de privacidade.

/v1/documents/fidelity/jobs

OCR documental assíncrono para fluxos que precisam preservar estrutura e páginas.

/v1/documents/review/jobs

Revisão estruturada de documento por job, com instruções e JSON Schema do resultado.

/v1/moderations

Mensagens avaliadas pela política da organização, com a nota de cada categoria.

/v1/images/generations e /v1/images/edits

Geração e edição de imagem por jobs assíncronos quando rn.images.* estiver disponível.

Rotas assíncronas retornam 202, status_url e result_url. Consulte GET /v1/jobs/{id} e GET /v1/jobs/{id}/result. Payloads e resultados ficam cifrados e expiram automaticamente depois de 24 horas.

curl https://rota-nacional.ia.br/v1/audio/compositions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -F "voice=@narracao.mp3" \
  -F "background=@trilha.mp3" \
  -F "background_gain_db=-18"

Moderação por política

Aplique a política da sua empresa a cada mensagem.

Escreva até 16 categorias em texto: o nome, quando sinalizar e, se quiser, o que não conta e a exceção. Cada mensagem volta com a decisão e a nota de 0 a 1 de cada categoria. Para mudar a política, mude o texto: não há modelo para treinar. Sem política, valem as regras gerais de segurança, como violência, ódio e fraude.

curl https://rota-nacional.ia.br/v1/moderations \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": ["Sua conta foi bloqueada. Faça um Pix de R$ 1 para liberar."],
    "categories": [{
      "name": "Golpe",
      "violation": "Pedir Pix ou código fingindo ser o banco.",
      "not_violation": "Dúvida comum sobre pagamento ou boleto."
    }]
  }'

{
  "object": "moderation",
  "model": "rota/moderacao",
  "mode": "policy",
  "results": [{
    "flagged": true,
    "score": 0.97,
    "cutoff": 0.335,
    "categories": { "Golpe": true },
    "category_scores": { "Golpe": 0.97 },
    "category_cutoffs": { "Golpe": 0.335 }
  }]
}

O formato é o da moderação da OpenAI, e a política vai no campo extra categories. A barreira tira os dados pessoais antes do modelo, e a resposta não repete o texto. A nota é uma estimativa: teste a política com mensagens reais antes de bloquear alguém. A primeira mensagem depois de uma pausa leva alguns segundos a mais, porque o modelo sobe nessa hora.

Preços

Pague em reais, por uso, só pelo que a API entrega.

Cada chamada às capacidades rn.* pela chave de API paga as suas unidades com o saldo da organização. O saldo entra por Pix no painel, em pacotes de R$ 10, R$ 25, R$ 50 ou R$ 100. Sem saldo, a chamada pode pagar sozinha por x402: envie X-PAYMENT com USDC na Base, a partir de US$ 0,001 por chamada. O laboratório do painel continua grátis, com limite de usos por dia.

O saldo é o crédito da casa: o código cred_ comprado em qualquer produto nosso também paga aqui, enviado em Authorization: Bearer ou em X-Credito; o que sobra fica nele.

Sem saldo nem pagamento, a resposta é 402, com o accepts do x402, o preco_brl e o buy_credit_url. O débito do saldo volta se o job falhar, for cancelado ou vencer na fila. O OCR reserva o máximo de páginas (max_pages, padrão 40) e devolve as que não leu. O pagamento por x402 vale para a chamada aceita e não volta automaticamente.

Sem chave e sem conta, a API também aceita x402: a rota paga responde 402 com o preço e o accepts, e você repete o pedido com X-PAYMENT. A carteira que paga vira a sua conta aqui: o uso, os jobs e o saldo que sobra ficam nela. Para usar esse saldo, envie X-Carteira com o endereço; o 402 pede só a diferença. No chat, o preço é o teto do pedido (max_tokens, padrão 1.024), e a sobra fica na carteira. O job assíncrono se acompanha pelo token das URLs do 202.

Testar grátis no laboratório

Opcional

Liste modelos disponíveis.

curl https://rota-nacional.ia.br/v1/models \
  -H "Authorization: Bearer $ROTA_API_KEY"

IDs atuais do catálogo:

• rota/resumo
• rota/analise
• rota/codigo
• rota/agentes
• rota/rapido
• rota/raciocinio
• rota/instrucao
• rota/contexto-longo
• rota/local
• rota/auto

Inferência opcional

Use chat completion quando a Rota também for o destino de IA.

curl https://rota-nacional.ia.br/v1/chat/completions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rota/resumo",
    "messages": [
      { "role": "user", "content": "Explique a Rota Nacional em uma frase." }
    ],
    "max_tokens": 80
  }'

Compare modelos e conecte sua aplicação.

Em API → Ferramentas, envie um pedido para um ou dois modelos. Confira a resposta, o tempo e os tokens. Cada modelo usa uma chamada da cota ou do crédito da organização.

Em Conectar aplicação, copie um exemplo em curl, JavaScript, Python ou JSON. Defina ROTA_API_KEY com uma chave da sua conta. O exemplo usa o endereço do ambiente aberto.

Abrir ferramentas

Na administração, confira chaves, saldo e catálogo do provedor. Cadastre rotas, defina permissões por organização e escolha o critério de seleção. A recuperação de falhas usa apenas rotas autorizadas com o mesmo preço ao cliente.

Usando o SDK OpenAI.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROTA_API_KEY,
  baseURL: "https://rota-nacional.ia.br/v1"
});

const resposta = await client.chat.completions.create({
  model: "rota/resumo",
  messages: [
    { role: "user", content: "ping" }
  ]
});

console.log(resposta.choices[0]?.message?.content);

Parâmetros

O que o corpo da requisição aceita.

model

Obrigatório. ID do catálogo (rota/codigo, rota/auto etc.).

messages

Obrigatório. Lista não vazia de { role, content }, papéis system/user/assistant/tool.

max_tokens

Opcional. Limite de tokens de saída.

temperature

Opcional. Aleatoriedade da resposta.

stream

Opcional. true para SSE (ver seção Streaming).

tools / tool_choice

Opcional. Ver seção Tool calling abaixo.

Streaming

Receba SSE ponta a ponta.

curl -N https://rota-nacional.ia.br/v1/chat/completions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rota/resumo",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Responda em tópicos curtos." }
    ]
  }'

Tool calling

Defina ferramentas e receba chamadas estruturadas.

Envie tools no formato OpenAI (function com name, description e parameters em JSON Schema). O suporte real de execução depende do modelo escolhido — rota/agentes e rota/codigo são curados para esse uso; rota/auto direciona automaticamente pra rota/agentes quando detecta uso de ferramentas na conversa.

curl https://rota-nacional.ia.br/v1/chat/completions \
  -H "Authorization: Bearer $ROTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rota/agentes",
    "max_tokens": 300,
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Retorna o clima de uma cidade",
        "parameters": { "type": "object", "properties": { "city": { "type": "string" } }, "required": ["city"] }
      }
    }],
    "messages": [{ "role": "user", "content": "Qual o clima em Recife?" }]
  }'

Privacidade

PII vira marcador antes de seguir.

A política padrão substitui dados pessoais por marcadores por request. O painel mostra categorias e contagens tratadas; conteúdo bruto e payload limpo ficam em arquivo cifrado de auditoria quando a retenção está habilitada, com purge definido pela administração.

Categorias médicas básicas já entram na camada determinística: cns, crm, prontuario, convenio e data_clinica.

{
  "entrada": "Meu CPF é 452.198.736-28",
  "limpo": "Meu CPF é [CPF_1]"
}

Método e evidência

Conheça o detector antes de integrar.

Nomes de pessoas passam primeiro pelo motor neural rn-privacy-0.2.0, executado em São Paulo, que devolve só posições. Depois, as regras rules-v1 aplicam padrões textuais e checksum de CPF/CNPJ numérico. Valores de texto em objetos e arrays são percorridos; chaves JSON e números não são tratados como strings. CNS e CRM usam contexto e formato, sem a mesma validação matemática.

O motor usa MiniLM, DistilBERT, ONNX e projeção Unicode. Se ele estiver indisponível, a requisição falha com 503 e nada segue adiante; textos acima de 256 KB recebem 413. Os escores do detector não são garantia de anonimização.

Consulte a documentação de engenharia para conhecer os efeitos de cada política, o contrato de spans, os limites, o formato cifrado e as referências científicas. Os benchmarks e dados para download permitem recalcular precisão, recall e cobertura de nomes em 46 textos sintéticos.

Roadmap · ainda indisponível

Proteção local, agentes e integrações.

Extensão e aplicativo desktop, substituição contextual, restauração autorizada, ferramentas e proxy MCP, CLI, SDK, conectores empresariais, SSO e implantação dedicada estão planejados. Esses recursos ainda não têm contrato público de API nem data de lançamento.

As rotas documentadas acima continuam sendo o contrato disponível. A conexão de agentes pela API de inferência não equivale a um servidor MCP de privacidade. Consulte a apresentação da plataforma e seu roadmap ou baixe o PDF comercial.

Erros

Formato JSON estável: { "error": { "message", "type", "code" } }.

400

invalid_json, missing_privacy_input, model_not_found ou invalid_messages — requisição malformada.

401

invalid_api_key — chave ausente ou inválida.

402

insufficient_balance — o saldo não cobre a chamada a uma capacidade rn.*; o corpo traz o accepts do x402 e onde comprar crédito.

403 · modelo

model_disabled — modelo desabilitado para esta conta.

403 · conta

account_suspended, trial_expired ou account_pending_approval — conta sem uso liberado.

404

not_found — rota inexistente.

413

privacy_text_too_large — texto acima de 256 KB por requisição para a detecção de nomes.

422

pii_blocked — política da organização bloqueou o payload sensível.

429

rate_limited, quota_requests_exceeded ou quota_tokens_exceeded — limite por minuto ou mensal.

502

upstream_error — falha ao consultar o modelo.

503

audit_archive_key_not_configured — auditoria temporariamente indisponível (config administrativa).

503 · worker

capability_unavailable — nenhum worker atende a capacidade agora; nada foi cobrado.

503 · nomes

person_engine_unavailable ou person_engine_daily_limit — detecção de nomes indisponível; nada foi enviado adiante.