Créditos e modos de análise

O sistema de créditos é a unidade de consumo da Scoring API do vario. Esta página explica o que é um crédito, como ele é descontado de acordo com o modo de análise escolhido, como consultar o saldo e o que acontece quando os créditos se esgotam.

1. O que é um crédito

Um crédito é a unidade mínima de consumo da API. Cada chamada a POST /api/v1/analyze desconta créditos do saldo do tenant antes de executar a análise. Créditos não são descontados por chamadas que retornam erro HTTP (por exemplo, 400, 401, 422).

Os créditos são pré-pagos: são adquiridos antes do uso. Não existe consumo pós-crédito nem débito automático.

2. Modos de análise e seu custo

Cada requisição a /api/v1/analyze aceita um campo mode que determina a profundidade da análise e a quantidade de créditos descontados.

screening

O modo screening executa apenas a camada L1: detecção por palavras-chave e similaridade semântica via embeddings. Não invoca nenhum LLM. É o modo mais econômico (1 crédito) e o mais rápido, projetado para descartar a maior parte de um corpus grande antes de aplicar análises mais custosas.

A resposta no modo screening tem um schema diferente dos modos fast e full: fornece pontuações da camada L1 (l1_score, l1_keyword_score, l1_embedding_score) e os termos identificados, mas não inclui campos L2/L3 como combined_score, should_alert, reasoning ou regulatory_frameworks. Veja Objeto response para a referência completa do schema de screening.

{
  "text": "Combinamos com o outro grupo não mexer no preço.",
  "playbook": "price_fixing",
  "language": "pt",
  "mode": "screening"
}

fast

O modo fast executa as camadas L1 e L2 (LLM leve). Oferece precisão moderada com baixa latência. É o modo recomendado para a segunda etapa de um funil de análise: recebe os documentos que superaram o limiar de screening e os classifica antes de escalar os mais relevantes para full.

{
  "text": "Combinamos com o outro grupo não mexer no preço.",
  "playbook": "price_fixing",
  "language": "pt",
  "mode": "fast"
}

full

O modo full executa as três camadas (L1 + L2 + L3 com LLM profundo). Oferece maior precisão e raciocínio mais detalhado no campo reasoning. É o modo padrão se mode não for especificado na requisição.

{
  "text": "Combinamos com o outro grupo não mexer no preço.",
  "playbook": "price_fixing",
  "language": "pt",
  "mode": "full",
  "thread_context": [
    "Reunião de amanhã: definimos as faixas de preço para o Q3.",
    "Os colegas da concorrência nos ligaram para alinhar."
  ]
}

3. Período de teste gratuito

Ao se cadastrar, cada conta recebe 250 créditos gratuitos. Não é necessário cartão de crédito para acessar o período de teste.

Com 250 créditos você pode executar até 250 chamadas no modo screening, 125 no modo fast ou 83 no modo full. É suficiente para avaliar o sistema com corpora reais antes de se comprometer com uma recarga.

O cadastro é feito via o endpoint público POST /api/public/api-signup ou pelo portal.

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "org_name": "Escritório Forense LATAM"}'

{
  "key": "vario_xbGhABC123...WXYZ",
  "warning": "Store this key immediately. It cannot be recovered — only revoked and replaced.",
  "free_credits": 250,
  "call_cost_screening": 1,
  "call_cost_fast": 2,
  "call_cost_full": 3
}

4. Recargas de créditos

Quando os créditos do período de teste se esgotarem, você pode recarregar pelo portal escolhendo o valor em USD que deseja carregar. Os preços são em USD; o Paddle atua como Merchant of Record e determina e recolhe os impostos correspondentes de acordo com a jurisdição do comprador.

Para empresas com número fiscal válido (CNPJ, RUT, RFC, CUIT, RUC, VAT number), o imposto pago no checkout é recuperável como crédito fiscal.

Veja a referência completa do checkout em Compra de créditos.

5. Consultar o saldo de créditos

Use o endpoint GET /api/v1/api-keys/credits para obter o saldo atual e a estimativa de chamadas restantes por modo.

curl https://api.vario.lat/api/v1/api-keys/credits \
  -H "Authorization: Bearer vario_SUA_API_KEY"

Resposta 200:

{
  "balance": 487,
  "call_cost_screening": 1,
  "call_cost_fast": 2,
  "call_cost_full": 3,
  "estimated_calls_remaining_screening": 487,
  "estimated_calls_remaining_fast": 243,
  "estimated_calls_remaining_full": 162
}

6. O que acontece quando os créditos se esgotam

Se o saldo chegar a zero, o endpoint POST /api/v1/analyze retorna 402 INSUFFICIENT_CREDITS:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Credit balance is 0. Top up credits to continue."
  }
}

Nenhum crédito é descontado nesse caso. A requisição não é processada.

Opções para continuar:

1. Pelo portal — faça login e recarregue créditos na seção de cobrança.
2. Pela API — consulte as opções com GET /api/public/checkout/credits/preview e inicie o checkout com POST /api/public/checkout/credits. Veja Compra de créditos.

7. Boas práticas para uso eficiente de créditos

O custo por análise varia 3x entre os modos. Um funil de três etapas reduz o consumo significativamente sem sacrificar precisão onde ela importa.

Padrão recomendado — funil de três etapas:

1. screening — varre o corpus completo com a camada L1 (keyword + embedding, sem LLM). Descarta os documentos sem sinal. Custo: 1 crédito por mensagem.
2. fast — analisa apenas os documentos que superaram o limiar de screening. Custo: 2 créditos por mensagem, aplicado a uma fração do corpus.
3. full — processa em profundidade apenas os documentos com sinal significativo no fast. Custo: 3 créditos por mensagem, aplicado à menor fração.

# Exemplo de funil de três etapas
for message in corpus:
    # Etapa 1: descarte massivo com screening (1 crédito)
    result_screening = analyze(message, mode="screening")
    if result_screening["l1_score"] < 0.3:
        continue  # sinal fraco → descartar

    # Etapa 2: classificação com fast (2 créditos)
    result_fast = analyze(message, mode="fast")
    if not result_fast["should_alert"]:
        continue  # abaixo do limiar → descartar

    # Etapa 3: análise profunda com full (3 créditos)
    result_full = analyze(message, mode="full")
    # Usar result_full para revisão jurídica

Outras recomendações:

• Monitore o campo balance periodicamente com GET /api/v1/api-keys/credits. Implemente alertas quando o saldo cair abaixo de um limiar operacional definido pela sua equipe.
• Use thread_context apenas em chamadas full onde o contexto do thread agrega valor. Nos modos screening e fast o campo é ignorado ou tem impacto limitado.
• Não use thread_context para fragmentar mensagens que excedem o limite de caracteres de text. Para documentos longos, envie chunks independentes.