Visión general
Jev evalúa un state — un ticket de soporte, un registro de chat, una llamada a herramienta, cualquier texto o JSON — contra un conjunto de preguntas tipadas y devuelve respuestas estructuradas sobre las que tu código puede ramificar. No genera texto.
Una petición puede formular hasta 8 preguntas; se evalúan juntas y comparten el coste de entrada del state. El cuerpo de la petición tiene la misma forma que acepta la API SystemOne de TypeSafe — para migrar una integración que funciona, cambia la URL base y la clave Bearer.
- POST
https://jevmodel.org/v1/systemone— el único endpoint de decisiones. - CORS está abierto (
access-control-allow-origin: *), el endpoint responde desde cualquier origen. Mantén tu clave en un servidor de todos modos. - El playground envía exactamente la misma petición a través de tu sesión de navegador — lo que previsualizas ahí es lo que envías.
Autenticación
Cada llamada a la API necesita una clave de jevmodel.org. Créala en Dashboard → API keys; las claves empiezan por sk- y se muestran una sola vez al crearlas. Guárdala como variable de entorno, por ejemplo JEVMODEL_API_KEY.
Authorization: Bearer $JEVMODEL_API_KEY Las claves pertenecen al saldo de tokens de tu cuenta y pueden revocarse desde el dashboard. Nunca pongas una clave en código del lado del cliente ni la subas a un repositorio — si se filtra, revócala y genera otra. El playground se autentica con tu sesión de navegador y no necesita clave.
Endpoint HTTP
Envía un cuerpo JSON al endpoint de evaluación con autenticación Bearer:
POST /v1/systemone HTTP/1.1
Host: jevmodel.org
Authorization: Bearer $JEVMODEL_API_KEY
Content-Type: application/json
Idempotency-Key: ticket-4821-run-1 # optional Idempotency-Key es opcional (hasta 100 caracteres). Los reintentos con la misma clave reutilizan el registro de facturación original, así que una petición reintentada no se cobra dos veces por la misma entrada.
curl -X POST https://jevmodel.org/v1/systemone \
-H "Authorization: Bearer $JEVMODEL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "jev-latest",
"state": "The customer has been billed twice and wants a refund today.",
"questions": {
"route": {
"type": "choice",
"instructions": "Which queue should own this ticket?",
"criteria": {
"billing": "Payments, refunds, invoices",
"technical": "Product errors and usage problems",
"sales": "Pricing, upgrades, new business"
}
},
"escalate": {
"type": "noul",
"instructions": "Does this need a human right now?"
},
"urgency": {
"type": "score",
"instructions": "How urgent is this for the customer?",
"criteria": ["routine", "soon", "urgent", "critical"]
}
}
}' Cuerpo de la petición
Un objeto JSON con un state y un mapa de preguntas:
{
"model": "jev-latest",
"state": "The customer has been billed twice and wants a refund today.",
"questions": {
"route": {
"type": "choice",
"instructions": "Which queue should own this ticket?",
"criteria": {
"billing": "Payments, refunds, invoices",
"technical": "Product errors and usage problems",
"sales": "Pricing, upgrades, new business"
}
},
"escalate": {
"type": "noul",
"instructions": "Does this need a human right now?"
},
"urgency": {
"type": "score",
"instructions": "How urgent is this for the customer?",
"criteria": ["routine", "soon", "urgent", "critical"]
}
}
} | Campo | Tipo | Notas |
|---|---|---|
model | string | Opcional; por defecto jev-latest. |
state | string, object o array | Obligatorio. La forma serializada admite hasta 1.000.000 caracteres. |
questions | object | Mapa obligatorio de 1–8 nombres de pregunta a definiciones tipadas. Los nombres son identificadores: letras, dígitos y _, máximo 64 caracteres. |
assets | object | Opcional (experimental). Hasta 4 imágenes PNG/JPEG con un nombre de referencia que se escribe dentro de state, instructions o criteria. Ver Imágenes y Box. |
Cada pregunta necesita un type e instructions (hasta 1.800 caracteres) indicando al modelo qué decidir. criteria aporta el espacio de respuesta — obligatorio para choice y score, opcional para noul.
Tipos de pregunta
Elige la forma de respuesta que tu aplicación pueda usar.
| Tipo | Criteria | Respuesta |
|---|---|---|
noul | Descripciones opcionales de las etiquetas true / false. | noul — la probabilidad de sí, de 0 a 1. |
choice | Objeto de 2–20 claves de opción con descripciones. | choice seleccionada, un mapa probabilities y confidence. |
score | Array ordenado de 2–10 niveles. | score numérico (puede ser fraccionario) y confidence. |
box | No se usa — solo instructions. | box con bordes normalizados (top/bottom/left/right, 0–1) y confidence. Experimental; requiere jev-preview. |
Los criteria serializados admiten hasta 2.000 caracteres por pregunta. Los fallos de validación devuelven 422 antes de reservar tokens — las peticiones incorrectas nunca se cobran.
Imágenes y Box (experimental)
Jev 1.14 acepta imágenes PNG y JPEG como entrada para decisiones — comprensión de imágenes, no generación. Adjunta cada imagen en assets con un nombre de referencia y escribe esa referencia dentro de state, en las instructions de una pregunta o en criteria; la referencia se resuelve a la imagen en esa posición. Las solicitudes con imágenes o Box necesitan el modelo de vista previa — usa jev-preview en model.
{
"model": "jev-preview",
"state": "Shipment photo attached as img-1.",
"assets": {
"img-1": { "type": "image", "format": "jpg", "data_base64": "/9j/4AAQSkZJRg…" }
},
"questions": {
"damage_visible": {
"type": "noul",
"instructions": "Is there visible damage to the package in img-1?"
},
"damage_region": {
"type": "box",
"instructions": "Locate the damaged area in img-1"
}
}
} assetsasigna una referencia a{ "type": "image", "format": "png|jpg", "data_base64": "…" }— máximo 4 imágenes, ~4 MB cada una tras codificar.- Cada asset debe estar referenciado y cada uso se factura — las imágenes cuentan para
usage.input_tokensigual que el texto. boxsolo tomainstructionsy siempre devuelve una caja — combínalo con una pregunta noul como «¿se ve X?» cuando el objetivo pueda no existir.- Es una superficie experimental opt-in: el proxy aplica el header upstream automáticamente cuando la solicitud lleva assets o una pregunta box. No se admiten subidas multipart — envía base64.
Audio y vídeo siguen sin soporte — conviértelos primero a texto o datos estructurados.
JSON de respuesta
Una respuesta 200 es la salida del modelo en sí: el modelo resuelto, una respuesta por nombre de pregunta y el uso. Los valores de abajo son ilustrativos — ejecuta la petición para una salida real.
{
"model": "jev-latest",
"answers": {
"route": {
"type": "choice",
"choice": "billing",
"probabilities": { "billing": 0.93, "technical": 0.05, "sales": 0.02 },
"confidence": 0.93
},
"escalate": {
"type": "noul",
"noul": 0.12
},
"urgency": {
"type": "score",
"score": 1.4,
"confidence": 0.88
}
},
"usage": { "input_tokens": 136, "output_tokens": 18 }
} answersva indexado por tus nombres de pregunta — lees los campos que pediste.- En
choice, ramifica por la etiqueta seleccionada e inspeccionaprobabilitiescuando necesites la distribución completa. noules P(sí) — tu código decide el umbral de acción.usage.input_tokenses lo que esta llamada cobró realmente; los tokens de salida son gratis.
Facturación
La API cobra solo tokens de entrada — la salida es gratis. Cada llamada se cobra según los usage.input_tokens reales que informa el modelo. Con tokens gratuitos se reserva una estimación por adelantado y luego se liquida a esa cifra. Si Jev falla en el upstream, no se cobra nada.
- Inicia sesión una vez y recibe 100.000 tokens de entrada gratis; los paquetes de pago empiezan en $9,90 y no caducan.
- Saldo insuficiente devuelve
402antes de llamar a Jev. X-Tokens-Remainingen cada respuesta 200 es tu saldo tras la liquidación.- Estímalo tú mismo:
Σ ceil((state + question).length / 4): el state cuenta una vez por pregunta.
Modelos y límites
jev-latest es el modelo por defecto y el que se sirve actualmente — el campo model es opcional. Las variantes Laya del playground están anunciadas y aún no están expuestas en este endpoint.
| Límite | Valor |
|---|---|
| Preguntas por petición | 8 |
| Nombre de pregunta | Identificador ≤ 64 caracteres |
state serializado | 1.000.000 caracteres |
instructions por pregunta | 1.800 caracteres |
| Opciones de choice / niveles de score | 2–20 opciones, 2–10 niveles |
criteria serializados | 2.000 caracteres por pregunta |
| Límite de tasa | 120 peticiones / minuto por clave |
Imágenes por solicitud (assets) | 4 |
| Formato / tamaño de imagen | PNG o JPEG en base64, ≤ ~4 MB cada una |
| Dimensiones de imagen | 256–1.568 px por lado |
Estas cifras describen el validador de la API; el modelo upstream puede tener sus propios límites de contexto.
Errores y reintentos
Los errores devuelven un sobre JSON con un type legible por máquina y un message para humanos:
{
"error": {
"type": "invalid_request_error",
"message": "At most 8 questions per request."
}
} | Estado | Tipo | Causa | ¿Cobrado? |
|---|---|---|---|
401 | authentication_error | Clave ausente, inválida o revocada. | No |
402 | insufficient_credits | Los tokens de entrada estimados superan tu saldo. | No |
422 | invalid_request_error | El cuerpo no pasó la validación — ver message. | No |
429 | rate_limit_error | Más de 120 peticiones este minuto. | No |
502 | upstream_error | Jev no pudo completar la llamada. | No — reembolsado |
Reintenta 429 y 502 con backoff exponencial — la ventana de tasa es por minuto, así que pausas cortas suelen bastar. Envía un Idempotency-Key al reintentar para que una petición repetida liquide contra el mismo registro de facturación en vez de cobrar dos veces.
Servidor MCP para agentes
jevmodel.org también ejecuta un servidor MCP remoto sobre Streamable HTTP en https://jevmodel.org/mcp. Expone cuatro herramientas — jev_decide (el contrato completo de state más questions), jev_noul, jev_choice y jev_score — para que agentes de código como Claude Code, Cursor o Cline llamen a Jev sin escribir HTTP.
claude mcp add --transport http jev https://jevmodel.org/mcp \
--header "Authorization: Bearer $JEVMODEL_API_KEY" - Misma clave
Authorization: Bearer sk-…y mismo saldo de tokens que esta API —tools/callcobra solo tokens de entrada. initialize,pingytools/listno requieren autenticación; solotools/callusa tu clave.GET /mcpdevuelve una tarjeta JSON de descubrimiento para agentes y humanos.
Los comandos de configuración para Claude Code y Cursor, y la skill de agente a juego (manual de juicio), están en la página de herramientas de agente.
Del playground a la API
Construye primero el escenario en el playground — la vista previa de la petición muestra el cuerpo JSON exacto que tu aplicación debe enviar, y Copy API example te da el cURL correspondiente. Cuando las respuestas convenzan, crea una clave en el dashboard y cambia la sesión del navegador por autenticación Bearer.
Más lectura: Cómo usar Jev recorre una primera llamada de principio a fin, y Ejemplos de la API de Jev tiene patrones de producción para cada tipo de pregunta.