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 —
criteriaes 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 —
criteriaes exactamente{ "true": …, "false": … }. La respuesta esnoul, una única probabilidad de que la afirmación sea cierta. Una respuesta noul no lleva campo de confianza: comparanoulcon tu propia banda. - score —
criteriaes un array de 2 a 7 niveles ordenados, de peor a mejor. La respuesta esscore, un valor continuo entre 0 y el índice del último nivel, más la distribución sobre los niveles y unlegendque asocia cada índice a su nivel. - El cuerpo de etiqueta única de clientes antiguos sigue funcionando: envía
instructionsylabels(una lista, o un objeto de etiqueta a guía) en lugar dequestions, y la respuesta llega con el idcategory.
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(aliasclef-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(aliasclef) — 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(aliasclef-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(aliaskev-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.
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.
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-flashycloudflare/clefse sirven directamente;jev,jev-latest,kevykev-latestsignifican 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ódigo | estado | qué significa | qué hacer |
|---|---|---|---|
invalid_request | 400 | el cuerpo está bien formado pero no es una petición válida | lee error; nombra el campo |
invalid_json | 400 | el cuerpo no es JSON | envía content-type: application/json |
empty_body | 400 | no hay cuerpo donde hace falta | envía el cuerpo JSON |
missing_field | 400 | falta un campo obligatorio | revisa la forma de la petición |
invalid_email | 400 | un campo que debe ser un correo no lo es | envía una dirección completa |
not_found | 404 | no existe la ruta, o no existe esa clave en la cuenta | revisa la ruta o el id |
key_missing | 401 | falta la cabecera authorization en un endpoint que la exige | envía Bearer cfl_… |
key_malformed | 401 | la cabecera existe pero no es una clave cfl_… | copia la clave entera, sin comillas |
key_unknown | 401 | la clave no existe o ha sido revocada | genera una nueva en /api-keys |
plan_ended | 402 | el plazo de pago de esta cuenta ha terminado | renueva en /pricing; las claves vuelven a activarse |
credit_exhausted | 402 | el crédito del mes se ha agotado; el recuento diario de llamadas es otro límite distinto | compra un paquete de crédito o espera al reinicio mensual; resetsOn indica la fecha |
quota_exceeded | 429 | las decisiones de hoy para este plan están agotadas | espera al reinicio diario; limit da la cifra del plan |
key_limit | 409 | este plan ya tiene el máximo de claves activas | revoca una, o sube de plan |
rate_limited | 429 | una 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 dimensionar | espera un segundo y reintenta |
concurrency_exceeded | 429 | más peticiones en vuelo de las que permite el plan | espera a que termine una de tus propias llamadas; retry-after es 1 |
payload_too_large | 413 | el cuerpo supera el límite en bytes | el mensaje indica ambas cifras |
state_too_large | 413 | el estado supera lo que lee el modelo que nombraste | acorta el estado o nombra un modelo mayor |
model_rejected | 400 | el proveedor rechazó la petición | el mensaje incluye el motivo del proveedor |
model_unavailable | 502 | no se pudo alcanzar el modelo | no se cobró nada; reintenta |
model_not_configured | 503 | este despliegue no tiene modelo configurado | reintentar no ayudará; escríbenos |
gateway_not_configured | 503 | la pasarela de pago no está aprovisionada | reintenta en un minuto; ya tenemos la alerta |
internal_error | 500 | todo lo que no hemos clasificado | reintenta una vez y escríbenos con la hora |
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.
| plan | decisiones / día | peticiones en vuelo | cuerpo | estado | imágenes | claves |
|---|---|---|---|---|---|---|
| playground (sin clave) | 25 por sesión | sin límite | 64 KB | 8.000 caracteres | ninguna | — |
| Pro | 2.000 | 8 | 8 MB | 200.000 caracteres | 4 | 1 |
| Scale | 20.000 | 32 | 8 MB | 200.000 caracteres | 4 | 3 |
| Studio | 40.000 | 64 | 8 MB | 200.000 caracteres | 4 | 10 |
| Agency | 100.000 | 128 | 8 MB | 200.000 caracteres | 4 | 40 |
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.
| plan | crédito / mes | tiempo de modelo incluido |
|---|---|---|
| Pro | 6 | $3.00 |
| Scale | 40 | $20.00 |
| Studio | 72 | $36.00 |
| Agency | 180 | $90.00 |
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.
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.