Créditos y modos de análisis

El sistema de créditos es la unidad de consumo de la Scoring API de vario. Esta página explica qué es un crédito, cómo se descuenta según el modo de análisis elegido, cómo consultar el saldo y qué sucede cuando se agotan.

1. Qué es un crédito

Un crédito es la unidad mínima de consumo de la API. Cada llamada a POST /api/v1/analyze descuenta créditos del balance del tenant antes de ejecutar el análisis. No se descuentan créditos por llamadas que retornan error HTTP (por ejemplo, 400, 401, 422).

Los créditos son prepagos: se adquieren antes de usarlos. No existe consumo posterior a crédito ni deuda automática.

2. Modos de análisis y su costo

Cada request a /api/v1/analyze acepta un campo mode que determina la profundidad del análisis y la cantidad de créditos descontados.

screening

El modo screening ejecuta únicamente la capa L1: detección por palabras clave y similitud semántica mediante embeddings. No invoca ningún LLM. Es el modo más económico (1 crédito) y el más rápido, diseñado para descartar el grueso de un corpus grande antes de aplicar análisis más costosos.

El response en modo screening tiene un schema diferente al de los modos fast y full: entrega puntajes de la capa L1 (l1_score, l1_keyword_score, l1_embedding_score) y las frases clave identificadas, pero no incluye campos L2/L3 como combined_score, should_alert, reasoning ni regulatory_frameworks. Ver Objeto response para la referencia completa del schema de screening.

{
  "text": "Hablamos con los del otro grupo y acordamos no movernos del precio.",
  "playbook": "price_fixing",
  "language": "es",
  "mode": "screening"
}

fast

El modo fast ejecuta las capas L1 y L2 (LLM ligero). Ofrece precisión moderada con baja latencia. Es el modo recomendado para el segundo paso de un embudo de análisis: recibe los documentos que superaron el umbral de screening y los clasifica antes de escalar los más relevantes a full.

{
  "text": "Hablamos con los del otro grupo y acordamos no movernos del precio.",
  "playbook": "price_fixing",
  "language": "es",
  "mode": "fast"
}

full

El modo full ejecuta las tres capas (L1 + L2 + L3 con LLM profundo). Entrega mayor precisión y razonamiento más detallado en el campo reasoning. Es el modo por defecto si no se especifica mode en el request.

{
  "text": "Hablamos con los del otro grupo y acordamos no movernos del precio.",
  "playbook": "price_fixing",
  "language": "es",
  "mode": "full",
  "thread_context": [
    "Reunión de mañana: definimos rangos de precios para Q3.",
    "Los colegas de la competencia nos llamaron para coordinar."
  ]
}

3. Trial gratuito

Al registrarse, cada cuenta recibe 250 créditos gratuitos. No se requiere tarjeta de crédito para acceder al trial.

Con 250 créditos puedes ejecutar hasta 250 llamadas en modo screening, 125 en modo fast o 83 en modo full. Es suficiente para evaluar el sistema con corpus reales antes de comprometerte con una recarga.

El registro se realiza vía el endpoint público POST /api/public/api-signup o desde el portal.

curl -X POST https://api.vario.lat/api/public/api-signup \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "org_name": "Firma 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

Cuando los créditos del trial se agoten, puedes recargar desde el portal eligiendo el monto en USD que quieras cargar. Los precios son en USD; Paddle actúa como Merchant of Record y determina y remite los impuestos correspondientes según la jurisdicción del comprador.

Para empresas con número fiscal válido (CUIT, RFC, CNPJ, RUT, RUC, VAT number), el impuesto pagado en checkout es recuperable como crédito fiscal.

Ver la referencia completa de checkout en Compra de créditos.

5. Consultar el saldo de créditos

Usa el endpoint GET /api/v1/api-keys/credits para obtener el balance actual y la estimación de llamadas restantes según cada modo.

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

Response 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. Qué pasa cuando se agotan los créditos

Si el balance llega a cero, el endpoint POST /api/v1/analyze retorna 402 INSUFFICIENT_CREDITS:

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

Ningún crédito se descuenta en este caso. El request no se procesa.

Opciones para continuar:

1. Desde el portal — inicia sesión y recarga créditos en la sección de billing.
2. Desde la API — consulta las opciones con GET /api/public/checkout/credits/preview e inicia el checkout con POST /api/public/checkout/credits. Ver Compra de créditos.

7. Buenas prácticas para uso eficiente de créditos

El costo por análisis varía 3x entre modos. Un embudo de tres etapas reduce el consumo significativamente sin sacrificar precisión donde importa.

Patrón recomendado — embudo de tres etapas:

1. screening — barre el corpus completo con la capa L1 (keyword + embedding, sin LLM). Descarta los documentos con señal nula. Costo: 1 crédito por mensaje.
2. fast — analiza únicamente los documentos que superaron el umbral de screening. Costo: 2 créditos por mensaje, aplicado a una fracción del corpus.
3. full — procesa en profundidad solo los documentos con señal significativa en fast. Costo: 3 créditos por mensaje, aplicado a la fracción más pequeña.

# Ejemplo de embudo de tres etapas
for message in corpus:
    # Etapa 1: descarte masivo con screening (1 crédito)
    result_screening = analyze(message, mode="screening")
    if result_screening["l1_score"] < 0.3:
        continue  # señal débil → descartar

    # Etapa 2: clasificación con fast (2 créditos)
    result_fast = analyze(message, mode="fast")
    if not result_fast["should_alert"]:
        continue  # no supera umbral → descartar

    # Etapa 3: análisis profundo con full (3 créditos)
    result_full = analyze(message, mode="full")
    # Usar result_full para revisión legal

Otras recomendaciones:

• Monitorea el campo balance periódicamente con GET /api/v1/api-keys/credits. Implementa alertas cuando el balance caiga por debajo de un umbral operativo definido por tu equipo.
• Usa thread_context solo en llamadas full donde el contexto del hilo agrega valor. En modo screening y fast el campo se ignora o tiene impacto limitado.
• No uses thread_context para fragmentar mensajes que superan el límite de caracteres de text. Para documentos largos, envía chunks independientes.