Documentación de la API de decisión

Dos endpoints, un solo modelo. Envía un estado y un esquema de preguntas tipadas, y recibe una probabilidad para cada opción permitida. Esta página es la referencia completa.

Dos endpoints, un modelo

POST /api/v1/decisions es el contrato systemone, la misma forma que sirve jevapi.pro: un estado más preguntas tipadas, cada una con su propio criteria. Requiere una clave de API y es el que conviene usar en un pipeline.

POST /api/decide es el contrato del playground: el mismo estado, pero cada pregunta es un prompt con una lista de options. Funciona sin clave y se cuenta por sesión de navegador, así que es el que llama la demo interactiva.

Para un ejemplo gratuito ejecutable, abre /es/playground, carga el ticket de soporte y pulsa Decidir. El resultado muestra cada probabilidad, el modelo y el proveedor reales, el requestId de esa llamada y la petición curl exacta para copiar. Repetirla usa la misma cuota de sesión; no emite reembolsos. El tiempo del navegador incluye red y servidor, se distingue del benchmark de Cloudflare y no es un SLA.

Ambos ejecutan el mismo modelo y devuelven las mismas probabilidades. Elige uno y quédate con él: cambiar de forma a mitad de proyecto no aporta nada.

Petición systemone

curl -X POST https://clef-flash.com/api/v1/decisions \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer cfl_0123456789abcdef0123456789abcdef' \
  -d '{
    "text": "Customer wrote: I was charged twice for the October invoice.",
    "questions": [
      {
        "id": "intent",
        "type": "choice",
        "instructions": "What does the customer want?",
        "criteria": {
          "billing": "a charge, invoice or refund",
          "technical": "something is broken or misbehaving",
          "cancellation": "they want to stop paying"
        }
      },
      {
        "id": "urgency",
        "type": "score",
        "instructions": "How quickly does this need a human?",
        "criteria": ["whenever", "this week", "today", "immediately"]
      }
    ],
    "threshold": 0.85
  }'

Tipos de pregunta

Cada pregunta declara qué clase de respuesta quiere, y criteria es donde vive ese dominio.

  • choice — criteria es un objeto de 2 a 12 etiquetas, cada una asociada a una línea de guía para el modelo. La respuesta es la etiqueta ganadora más la distribución completa.
  • noul — criteria es exactamente { "true": …, "false": … }. La respuesta es noul, una única probabilidad de que la afirmación sea cierta. Una respuesta noul no lleva campo de confianza: compara noul con tu propia banda.
  • score — criteria es un array de 2 a 7 niveles ordenados, de peor a mejor. La respuesta es score, un valor continuo entre 0 y el índice del último nivel, más la distribución sobre los niveles y un legend que asocia cada índice a su nivel.
  • El cuerpo de etiqueta única de clientes antiguos sigue funcionando: envía instructions y labels (una lista, o un objeto de etiqueta a guía) en lugar de questions, y la respuesta llega con el id category.

El cuerpo que ya envía un cliente jev

Los clientes de la familia systemone (Jev) indexan questions por id en vez de usar un array, y envían el estado como objeto JSON. Ese cuerpo funciona aquí sin cambios: el id sale de la clave.

model puede nombrar jev, jev-latest, kev o kev-latest; se leen como «el modelo de este endpoint» y se responden con el modelo de este despliegue. La respuesta siempre nombra el modelo que respondió de verdad, y cualquier otro nombre se rechaza en lugar de sustituirse.

Cuerpo estilo jev

{
  "model": "jev-latest",
  "state": { "page": { "h1": "Elegir una broca", "opening": "Elige la broca según el material." } },
  "questions": {
    "page_type": {
      "type": "choice",
      "instructions": "¿Qué clase de página es page?",
      "criteria": { "article_or_guide": "un artículo o guía editorial", "pricing": "planes o precios" }
    }
  }
}

Qué modelo responde

Tres proveedores publican modelos de decisión bajo este mismo contrato: un estado, preguntas tipadas y probabilidades calibradas. La forma de la petición es idéntica; los pesos, el precio y la ventana de contexto no lo son. Un nombre de familia no es un modelo: jev es de TypeSafe, kev es de Jared Palmer y clef es de Cloudflare.

Este despliegue sirve exactamente estos cuatro, y ningún otro. Nombrar uno de ellos es la única forma de fijar la respuesta a unos pesos concretos.

  • cloudflare/clef-flash (alias clef-flash) — Cloudflare, 9B, contexto de 24.576 tokens, hasta 120.000 caracteres de estado, texto e imágenes, 0,019 USD por millón de tokens de entrada. Es el predeterminado.
  • cloudflare/clef (alias clef) — Cloudflare, 27B, contexto de 16.384 tokens, hasta 80.000 caracteres, texto e imágenes, 0,042 USD por millón de tokens de entrada. Más lento y más preciso.
  • cloudflare/clef-omni (alias clef-omni) — Cloudflare, contexto de 65.529 tokens, hasta 200.000 caracteres, texto e imágenes, 0,15 USD por millón de tokens de entrada. Para estados que las ventanas menores recortarían.
  • jaredpalmer/kev-4b (alias kev-4b) — Jared Palmer, 4B, contexto de 8.192 tokens, hasta 20.000 caracteres, solo texto, 0,042 USD por millón de tokens de entrada.
  • jev, jev-latest, kev, kev-latest — alias, no modelos. Resuelven al modelo predeterminado de este despliegue, y la respuesta indica cuál fue.
Los tokens de salida no se facturan en ningún modelo de decisión: la respuesta es una distribución, no texto generado, así que todos los precios anteriores son solo de entrada.

Cuánto del estado lee el modelo

El cuerpo de una petición puede ser mucho más grande que la ventana de contexto del modelo, y esos dos límites no son el mismo límite. Las claves de pago aceptan cuerpos de hasta 8 MB; el estado tiene un tope por modelo, más abajo, y ese tope se aplica aquí antes de enviar nada.

Esos topes no son arbitrarios. Medido contra el endpoint en vivo, un estado de 150.011 caracteres enviado a cloudflare/clef-flash devolvió 200 y se facturó exactamente como 24.576 tokens de entrada —la ventana, con el resto descartado y sin error—, mientras que un estado de 170.011 caracteres del mismo texto se rechazó. cloudflare/clef factura 16.384 tokens en silencio para cualquier cosa que pase de ahí, sea cual sea el tamaño del estado. Que una petición demasiado grande se trunque o se rechace no es algo en lo que se pueda confiar, así que esta API nunca envía una.

La prosa en inglés ronda los 5,5 caracteres por token, de donde salen los topes en caracteres, con margen. El JSON, el código y los alfabetos no latinos se tokenizan más densamente, así que un estado aún puede superar la ventana y ser rechazado; recibes un 413 que nombra el límite del modelo y los tokens de este estado, no una respuesta truncada.

Una respuesta 200 significa que el modelo leyó el estado completo. Eso no siempre fue cierto antes de esta versión, y es la diferencia entre una respuesta defendible y una que solo lo parecía.

Si una decisión depende del final de un documento largo, sube el techo nombrando un modelo con una ventana mayor —cloudflare/clef-omni lee 65.529 tokens— en lugar de apostar al truncado.

La respuesta

Las respuestas van indexadas por id de pregunta, cada una con su type y una marca needsReview que se activa cuando el modelo está menos seguro que tu umbral. El nivel superior repite la primera pregunta como choice, confidence y probabilities, para que un cliente con una sola pregunta pueda ignorar el mapa.

Respuesta systemone

{
  "ok": true,
  "model": "cloudflare/clef-flash",
  "degraded": false,
  "latencyMs": 412,
  "plan": "clef-flash-pro",
  "usedToday": 17,
  "limit": 2000,
  "answers": {
    "intent": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.8126,
      "probabilities": { "billing": 0.8126, "technical": 0.118, "cancellation": 0.0694 },
      "needsReview": true
    },
    "urgent": { "type": "noul", "noul": 0.7491, "needsReview": true },
    "urgency": {
      "type": "score",
      "score": 2.4632,
      "confidence": 0.4633,
      "probabilities": { "0": 0.009, "1": 0.0196, "2": 0.4705, "3": 0.5009 },
      "legend": { "0": "whenever", "1": "this week", "2": "today", "3": "immediately" },
      "needsReview": true
    }
  },
  "choice": "billing",
  "confidence": 0.8126,
  "probabilities": { "billing": 0.8126, "technical": 0.118, "cancellation": 0.0694 },
  "needsReview": true
}

La respuesta del playground

/api/decide responde una entrada por pregunta, con option indicando la ganadora. provider dice quién respondió (openrouter para el modelo en vivo, fallback para el evaluador local) y requestId identifica esta llamada exacta en nuestros registros.

Ambos endpoints fallan cerrados: cuando el modelo en vivo no está disponible, /api/v1/decisions y /api/decide devuelven 502 model_unavailable y no se cobra nada. El evaluador léxico determinista es opcional — envía "allowDegraded": true en /api/decide — y toda respuesta suya lleva degraded: true, model: "fallback" y provider: "fallback". Nunca se devuelve sin etiquetar, y el endpoint systemone no degrada jamás.

Respuesta

{
  "ok": true,
  "model": "cloudflare/clef-flash",
  "provider": "openrouter",
  "degraded": false,
  "requestId": "0b6f4f4e-5a1e-4c1e-9d3e-2f6a1c9b7d20",
  "latencyMs": 412,
  "plan": "free",
  "usedToday": 3,
  "limit": 25,
  "answers": [
    {
      "id": "intent",
      "option": "billing",
      "confidence": 0.91,
      "probabilities": { "billing": 0.91, "technical": 0.04, "cancellation": 0.05 }
    }
  ]
}

Imágenes

Un estado puede ser una lista de partes de contenido, de modo que una captura de pantalla sea aquello sobre lo que se decide. Las imágenes deben ir incrustadas como data URL base64 — data:image/png;base64,…, JPEG o WebP. Una URL remota https:// se rechaza, porque el modelo no descarga URLs.

Los estados con imagen y los estados de más de 8.000 caracteres requieren una clave de pago. A quien llama gratis se le dice exactamente eso, en lugar de entregarle una respuesta truncada.

Estado con imagen

{
  "state": [
    { "type": "text", "text": "Which category does this receipt belong to?" },
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBORw0KGgo…" } }
  ],
  "questions": [
    { "id": "kind", "type": "choice", "instructions": "Pick the category", "criteria": { "meals": "food and drink", "travel": "transport and lodging" } }
  ]
}

Campos de la petición

Todos los campos se validan en el límite; una petición no válida se rechaza con un mensaje que nombra el valor problemático.

  • text (o su alias state) — cadena de 3 a 200.000 caracteres, un objeto JSON, o una lista de partes de contenido. Las peticiones gratuitas se limitan a 8.000 caracteres.
  • questions — de 1 a 8 preguntas, como array de { id, type, instructions, criteria } o como objeto indexado por id. Los ids cumplen ^[a-z][a-z0-9_]{0,31}$.
  • questions[].instructions — qué decidir, hasta 1.500 caracteres.
  • threshold — de 0.5 a 1, por defecto 0.85. Una respuesta por debajo vuelve con needsReview: true.
  • model — opcional. cloudflare/clef-flash y cloudflare/clef se sirven directamente; jev, jev-latest, kev y kev-latest significan el modelo de este despliegue. Cualquier otro nombre se rechaza en lugar de sustituirse en silencio.
  • Tamaño del cuerpo — 64 KB gratis, 8 MB con clave. Un cuerpo mayor se rechaza con 413 antes de analizarlo.

Errores por código

Toda negativa tiene la misma forma: ok: false, un code estable y un error legible. Decide por el código, no por la frase: la frase puede cambiar de redacción, un código nunca cambia de significado, y los códigos nuevos solo se añaden.

Toda respuesta y toda negativa de los dos endpoints de decisión llevan también un requestId, en el cuerpo y en la cabecera x-request-id: el mismo valor en ambos. Es el identificador que busca soporte, así que cítalo en lugar de la hora: un 429 que nunca llegó al modelo se rastrea igual que un 502 que sí llegó. El mensaje de error nombra el campo rechazado, nunca su contenido.

códigoestadoqué significaqué hacer
invalid_request400el cuerpo está bien formado pero no es una petición válidalee error; nombra el campo
invalid_json400el cuerpo no es JSONenvía content-type: application/json
empty_body400no hay cuerpo donde hace faltaenvía el cuerpo JSON
missing_field400falta un campo obligatoriorevisa la forma de la petición
invalid_email400un campo que debe ser un correo no lo esenvía una dirección completa
not_found404no existe la ruta, o no existe esa clave en la cuentarevisa la ruta o el id
key_missing401falta la cabecera authorization en un endpoint que la exigeenvía Bearer cfl_…
key_malformed401la cabecera existe pero no es una clave cfl_…copia la clave entera, sin comillas
key_unknown401la clave no existe o ha sido revocadagenera una nueva en /api-keys
plan_ended402el plazo de pago de esta cuenta ha terminadorenueva en /pricing; las claves vuelven a activarse
credit_exhausted402el crédito del mes se ha agotado; el recuento diario de llamadas es otro límite distintocompra un paquete de crédito o espera al reinicio mensual; resetsOn indica la fecha
quota_exceeded429las decisiones de hoy para este plan están agotadasespera al reinicio diario; limit da la cifra del plan
key_limit409este plan ya tiene el máximo de claves activasrevoca una, o sube de plan
rate_limited429una dirección que dispara más rápido de lo que el edge acepta: es una protección de ráfaga de mejor esfuerzo, no un límite del plan ni una cifra con la que dimensionarespera un segundo y reintenta
concurrency_exceeded429más peticiones en vuelo de las que permite el planespera a que termine una de tus propias llamadas; retry-after es 1
payload_too_large413el cuerpo supera el límite en bytesel mensaje indica ambas cifras
state_too_large413el estado supera lo que lee el modelo que nombrasteacorta el estado o nombra un modelo mayor
model_rejected400el proveedor rechazó la peticiónel mensaje incluye el motivo del proveedor
model_unavailable502no se pudo alcanzar el modelono se cobró nada; reintenta
model_not_configured503este despliegue no tiene modelo configuradoreintentar no ayudará; escríbenos
gateway_not_configured503la pasarela de pago no está aprovisionadareintenta en un minuto; ya tenemos la alerta
internal_error500todo lo que no hemos clasificadoreintenta una vez y escríbenos con la hora
Tres negativas comparten el 429 y piden reacciones distintas: quota_exceeded se reinicia al día siguiente, rate_limited se limpia en un minuto y concurrency_exceeded se limpia en cuanto termina una de tus propias llamadas — reintentarlo de inmediato es lo único que no funciona.

Cuotas por plan

Un plan vende decisiones por día y peticiones simultáneas en vuelo. No vende una tasa de peticiones: el caudal es la concurrencia dividida por la latencia, así que ocho peticiones en vuelo contra una respuesta de 1,3 segundos son unas seis respuestas por segundo — esa es la velocidad del modelo, no un límite que impongamos. Un modelo más rápido, o un estado más corto, la suben sin cambiar de plan.

El nivel gratuito cuenta por sesión de navegador y día; los niveles de pago cuentan por clave de API y día. Cada respuesta informa usedToday y limit, y GET /api/v1/usage devuelve toda la tabla de abajo para la clave con la que preguntas, así un cliente puede regularse en lugar de descubrir un límite con un 429.

plandecisiones / díapeticiones en vuelocuerpoestadoimágenesclaves
playground (sin clave)25 por sesiónsin límite64 KB8.000 caracteresninguna—
Pro2.00088 MB200.000 caracteres41
Scale20.000328 MB200.000 caracteres43
Studio40.000648 MB200.000 caracteres410
Agency100.0001288 MB200.000 caracteres440
La concurrencia se cuenta por clave y se publica desde esta versión; la llamada que la excede se responde y se registra hasta el 2026-11-10T00:00:00Z, y desde entonces se rechaza con concurrency_exceeded. La fecha está en /log. Consejo para lotes: incluye varias preguntas independientes sobre el mismo estado en una sola petición — cuesta una decisión, no una por pregunta.

El crédito de uso, definido

El crédito mide tiempo de modelo, no llamadas. Una llamada con un estado largo cuesta más que una con un estado corto, así que contar llamadas no basta para que el endpoint no opere con pérdidas: el crédito es el segundo límite que lo impide. Los dos límites se comprueban en cada petición y son independientes: el que se agote primero es la negativa que recibes. quota_exceeded es el recuento diario de llamadas; credit_exhausted es el tiempo de modelo del mes, y puede llegar mientras el recuento diario aún tiene margen.

Un crédito equivale a $0.50 de tiempo de modelo. A $0.019 por millón de tokens de entrada son 26,3 millones de tokens de entrada: unas 26.315 llamadas con un estado de 1.000 tokens.

La cuota de cada plan se reinicia el primer día del mes natural y no se acumula. Un paquete de crédito se compra una vez, no caduca nunca y solo paga las llamadas que superan la cuota del mes. Paquetes: Pack S 10 créditos ($5.00 de tiempo de modelo), Pack M 52 créditos ($26.00 de tiempo de modelo), Pack L 220 créditos ($110.00 de tiempo de modelo), Pack XL 900 créditos ($450.00 de tiempo de modelo). Una petición rechazada nunca llega al modelo, no se mide y no se cobra.

Cada respuesta lleva un bloque credit — periodo, fecha de reinicio, incluido, usado y restante. GET /api/v1/usage devuelve el mismo bloque más creditUnit, que indica cuánto vale un crédito en dólares, tokens de entrada y llamadas, para que un cliente convierta su consumo sin leer esta página. El cuerpo del 402 repite las cifras y añade topUpUrl y usageUrl.

plancrédito / mestiempo de modelo incluido
Pro6$3.00
Scale40$20.00
Studio72$36.00
Agency180$90.00
El crédito no es un contador de llamadas con otro nombre. Una llamada de 1.000 tokens y otra de 100.000 cuentan una vez cada una en la cuota diaria, pero solo la segunda consume crédito de forma apreciable: por eso la cuota diaria puede parecer intacta cuando llega un 402.

Tu primera petición, en JavaScript y Python

Los dos programas siguientes están completos. Guarda uno, pon en CLEF_FLASH_KEY la clave que llegó por correo con tu pedido y ejecútalo: Node 18 o posterior para el primero, Python 3.9 o posterior para el segundo, sin instalar ningún paquete. Una ejecución correcta imprime la etiqueta ganadora, la distribución completa y el requestId que soporte necesita para rastrear la llamada.

Ambos leen CLEF_FLASH_URL si está definida, así que el mismo archivo funciona contra un wrangler dev local sin editarlo. Ejecútalos en un servidor o en un proceso por lotes, nunca en el navegador: el navegador entregaría la clave a cada visitante. Si aún no tienes clave, el playground ejecuta el mismo modelo gratis.

La suite construye la petición desde la misma definición que llevan estos fragmentos y después ejecuta los dos programas tal cual contra el handler real por HTTP; si alguno deja de devolver una respuesta utilizable, la compilación falla. El código de esta página es el código que se ejecuta.

JavaScript (Node 18+)

const key = process.env.CLEF_FLASH_KEY;
if (!key) throw new Error('Set CLEF_FLASH_KEY to the key emailed with your order.');
const base = process.env.CLEF_FLASH_URL ?? 'https://clef-flash.com';

const response = await fetch(`${base}/api/v1/decisions`, {
  method: 'POST',
  headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
  body: JSON.stringify({
  "text": "Customer wrote: I was charged twice for the October invoice.",
  "questions": [
    {
      "id": "intent",
      "type": "choice",
      "instructions": "What does the customer want?",
      "criteria": {
        "billing": "a charge, invoice or refund",
        "technical": "something is broken or misbehaving",
        "cancellation": "they want to stop paying"
      }
    }
  ]
}),
});

const payload = await response.json();
if (!response.ok || payload.ok !== true) {
  console.error(payload.code ?? response.status, payload.error ?? 'request failed');
  process.exit(1);
}
const answer = payload.answers.intent;
console.log(answer.choice, answer.probabilities, `requestId=${payload.requestId}`);

Python 3.9+

import json
import os
import sys
import urllib.error
import urllib.request

key = os.environ.get("CLEF_FLASH_KEY")
if not key:
    sys.exit("Set CLEF_FLASH_KEY to the key emailed with your order.")
base = os.environ.get("CLEF_FLASH_URL", "https://clef-flash.com")

request = urllib.request.Request(
    base + "/api/v1/decisions",
    data=json.dumps({
  "text": "Customer wrote: I was charged twice for the October invoice.",
  "questions": [
    {
      "id": "intent",
      "type": "choice",
      "instructions": "What does the customer want?",
      "criteria": {
        "billing": "a charge, invoice or refund",
        "technical": "something is broken or misbehaving",
        "cancellation": "they want to stop paying"
      }
    }
  ]
}).encode(),
    method="POST",
    headers={"content-type": "application/json", "authorization": "Bearer " + key},
)
try:
    with urllib.request.urlopen(request, timeout=30) as response:
        payload = json.load(response)
except urllib.error.HTTPError as error:
    payload = json.load(error)
    print(payload.get("code", error.code), payload.get("error", "request failed"), file=sys.stderr)
    sys.exit(1)

answer = payload["answers"]["intent"]
print(answer["choice"], answer["probabilities"], "requestId=" + payload["requestId"])

Una primera ejecución correcta imprime

  • La etiqueta ganadora: billing, technical o cancellation.
  • La distribución sobre las tres etiquetas, sumando 1.
  • requestId=…: el identificador que hay que citar al preguntar a soporte por esa llamada.

Cuándo preferir el autoalojamiento

Si el estado contiene datos que no pueden salir de tu infraestructura, ejecuta el modelo tú mismo: los pesos son Apache 2.0. La guía para ejecutarlo localmente cubre el hardware y el comando de Ollama. La forma de la petición es la misma, así que el código que escribas contra esta API se traslada directamente.

Clef-Flash playground community-hosted

Community-hosted demo of the 9B model. Runs live in your browser session.

Preguntas frecuentes

¿Necesito una clave de API?

Para /api/v1/decisions, sí. El playground /api/decide funciona sin clave, contado por sesión de navegador; una clave de pago eleva la cuota diaria en ambos y sube el límite del cuerpo a 8 MB.

¿Puedo apuntar un cliente jevapi existente a este endpoint?

Sí, cambiando la URL base. El estado como objeto, las preguntas indexadas por id, los criteria por pregunta y un modelo jev-latest o kev se aceptan tal cual se envían. El mapa de respuestas usa los mismos ids y tipos, y las respuestas noul llevan el mismo campo noul; el resumen superior y los campos extra ok/latency/plan son aditivos.

¿Se almacena en caché la respuesta?

No. Cada petición ejecuta el modelo. Las peticiones idénticas no se deduplican, así que evita sondear el mismo estado en un bucle.

¿Qué modelo responde?

Clef-Flash por defecto. La respuesta nombra el modelo realmente utilizado y el proveedor que respondió. Ambos endpoints fallan cerrados: un fallo del proveedor es un 502 model_unavailable, nunca una conjetura. El respaldo determinista solo responde si quien llama a /api/decide envía "allowDegraded": true, y entonces informa degraded: true y provider: "fallback".

¿Necesitas más cuota?

Los planes de pago amplían el límite diario y emiten una clave de API. Consulta la página de precios o escríbenos para volúmenes altos.