# Guía API de Jev > Integra Jev con curl, Python y Node.js. Interpreta Choice, Score y Noul, elige la clave correcta y gestiona contexto, límites, errores y reintentos. - Canonical HTML: https://omniakey.com/es/blog/jev-api-guide - Markdown: https://omniakey.com/es/blog/jev-api-guide.md - Published: 2026-09-28 (updated 2026-10-24) - Author: Kiki, COO at OmniaKey - Language: es - Category: API setup - Reading time: 11 min - All posts: https://omniakey.com/blog/llms.txt --- La **API de Jev** evalúa un texto mediante preguntas definidas por tu aplicación. Envías `state`, `model` y un mapa `questions`; recibes decisiones tipadas en `answers`, con los mismos identificadores. No es una API de chat que devuelva un párrafo del que después tengas que extraer etiquetas. Esta guía cubre la integración. Para entender sus usos, precios y limitaciones, consulta la [explicación del modelo Jev](https://omniakey.com/es/blog/jev-model-explained). > **Revisado el 24 de octubre de 2026.** El contrato procede de la documentación de TypeSafe y la ruta del gateway se contrastó con la implementación de OmniaKey. Los ejemplos se comprobaron sin llamadas de pago; no son una prueba nueva de rendimiento. Los precios y límites directos no se trasladan automáticamente a un gateway. ## Elige el endpoint y la clave que le corresponde |Servicio|Endpoint POST|Credencial| |-|-|-| |OmniaKey|`https://api.omniakey.com/v1/alpha/search`|Clave de OmniaKey con acceso a `jev-latest`| |TypeSafe directo|`https://api.typesafe.ai/v1/systemone`|Clave de TypeSafe| Ambas rutas usan `Authorization: Bearer ...` y el cuerpo nativo de Jev. **No envíes una clave de un servicio al otro.** Tampoco sustituyas esta ruta por `/v1/chat/completions` ni `state` por `messages`: sería otro contrato. Crea una clave con permisos acotados, comprueba la [ruta actual de Jev](https://omniakey.com/es/jev-latest) y configura `OMNIAKEY_API_KEY` en tu entorno local. No la pongas en código del navegador, Git o capturas. La [guía de inicio de la API](https://docs.omniakey.com/es/quick-start) explica los pasos generales. ## Una solicitud JSON completa Guarda lo siguiente en `jev-request.json`. Una misma consulta decide el departamento, el grado de frustración y la urgencia de un mensaje de soporte. El ejemplo conserva el inglés porque TypeSafe lo identifica como su idioma más sólido; valida el español con muestras de tu propia aplicación. ```json { "model": "jev-latest", "state": "My payouts have failed for three days. Please help me resolve this today.", "questions": { "department": { "type": "choice", "instructions": "Which team should handle this message?", "criteria": { "billing": "Payments, invoices, or refunds", "technical": "Bugs, outages, or integrations", "sales": "Pricing, upgrades, or new accounts" } }, "frustration": { "type": "score", "instructions": "How frustrated is the customer?", "criteria": ["Calm", "Frustrated", "Very angry"] }, "is_urgent": { "type": "noul", "instructions": "Does the message express a time-sensitive need?" } } } ``` Los identificadores enlazan preguntas y respuestas. Según TypeSafe, esos nombres no participan en la inferencia: escribe la tarea en `instructions`, no solo en el nombre de la clave. `state` también admite objetos y arrays JSON con texto, como un registro de soporte con campos separados. ```bash curl --fail-with-body https://api.omniakey.com/v1/alpha/search \ -H "Authorization: Bearer $OMNIAKEY_API_KEY" \ -H "Content-Type: application/json" \ --data-binary @jev-request.json ``` Para acceder directamente a TypeSafe, cambia la URL por `https://api.typesafe.ai/v1/systemone` y utiliza `$TYPESAFE_API_KEY`. Conserva la estructura JSON y verifica qué identificadores acepta esa cuenta. ## Cómo interpretar Choice, Score y Noul |Tipo|Qué defines|Campos de respuesta|Interpretación| |-|-|-|-| |`choice`|Opciones con descripciones, hasta 255|`choice`, `probabilities`, `confidence`|Etiqueta elegida y distribución entre las opciones| |`score`|Rúbrica ordenada de 2–10 niveles|`score`, `legend`, `probabilities`, `confidence`|Nivel ponderado por probabilidades; puede ser decimal| |`noul`|Pregunta sí/no, con criterios `true` / `false` opcionales|`noul`|Probabilidad de sí entre 0 y 1, no un booleano| También recibes `model` y `usage.input_tokens` / `usage.output_tokens`. Actualmente `jev-latest` resuelve a `jev-1.14.0`, pero un alias puede cambiar. Registra la versión que respondió al evaluar el comportamiento; si necesitas fijarla, escribe `jev-1.14.0`. En una rúbrica de tres niveles, `1.05` está ligeramente por encima del nivel 1; no es una nota sobre 100. Interprétala con `legend`. Un Noul de `0.8` tampoco autoriza por sí solo un reembolso. Ajusta los umbrales con ejemplos etiquetados; `confidence` se deriva de la distribución y no garantiza que la decisión sea correcta. Esta respuesta completa es un ejemplo ilustrativo, no el resultado de una llamada real a la API. Los valores y los recuentos de tokens sirven para explicar la estructura; los resultados reales varían. ```json { "model": "jev-1.14.0", "answers": { "department": { "type": "choice", "choice": "billing", "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 }, "confidence": 0.81 }, "frustration": { "type": "score", "score": 1.05, "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" }, "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 }, "confidence": 0.92 }, "is_urgent": { "type": "noul", "noul": 0.8 } }, "usage": { "input_tokens": 320, "output_tokens": 72 } } ``` ## Ejemplos en Python y Node.js Ambos leen `jev-request.json` y hacen una sola petición. Imprimen las respuestas tipadas sin asumir que existe un campo OpenAI `choices`. Añade la política de reintentos acotados descrita más adelante para producción. ```python import json import os import urllib.error import urllib.request from pathlib import Path request = urllib.request.Request( "https://api.omniakey.com/v1/alpha/search", data=Path("jev-request.json").read_bytes(), headers={ "Authorization": f"Bearer {os.environ['OMNIAKEY_API_KEY']}", "Content-Type": "application/json", }, method="POST", ) try: with urllib.request.urlopen(request, timeout=30) as response: result = json.load(response) except urllib.error.HTTPError as error: raise SystemExit(f"Jev request failed: HTTP {error.code}") from None print(result["model"]) print(json.dumps(result["answers"], indent=2)) ``` ```javascript import { readFile } from 'node:fs/promises'; const key = process.env.OMNIAKEY_API_KEY; if (!key) throw new Error('Set OMNIAKEY_API_KEY first'); const response = await fetch('https://api.omniakey.com/v1/alpha/search', { method: 'POST', headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json', }, body: await readFile('jev-request.json', 'utf8'), signal: AbortSignal.timeout(30_000), }); if (!response.ok) throw new Error(`Jev request failed: HTTP ${response.status}`); const result = await response.json(); console.log(result.model); console.log(result.answers); ``` Usa Python 3 o una versión de Node.js con `fetch` y `AbortSignal.timeout`. Son ejemplos HTTP, no una afirmación de compatibilidad nativa con el SDK de OpenAI. TypeSafe también documenta sus propios SDK en la [referencia oficial](https://docs.typesafe.ai/api). ## Contexto, límites de llamadas y facturación Debes cumplir dos condiciones: **64K tokens para la solicitud completa** y **32K para `state` más la pregunta individual más larga**. Elimina contenido irrelevante y agrupa solo preguntas que necesiten el mismo estado. TypeSafe publica **250,000 tokens por segundo y 1,200 solicitudes por minuto**, sujetos a cambios durante el acceso inicial. Son límites de cuenta, no velocidad de una petición ni una promesa para OmniaKey. El gateway puede aplicar límites adicionales. El precio directo es **$0.042 por millón de tokens de entrada**, con salida gratuita en la fecha de revisión. La respuesta sigue incluyendo el consumo de salida. Eso no hace gratuita toda la API ni demuestra que el gateway use la misma unidad de cobro. Consulta el precio vigente y tus registros; el [artículo del modelo](https://omniakey.com/es/blog/jev-model-explained) explica el contexto de esos importes. El catálogo actual de Jev en OmniaKey aplica **cobro por solicitud**. Comprueba el precio vigente del modelo y los registros del panel antes de estimar el coste del gateway. ## Errores y reintentos |Estado de TypeSafe directo|Qué revisar|Acción| |-|-|-| |`401`|Servicio de la clave y cabecera Bearer|Corrige la credencial; no repitas una clave inválida| |`422`|Campos obligatorios, tipo y `criteria`|Corrige el campo indicado por el error| |`429`|Límite de solicitudes o tokens|Respeta `Retry-After` si existe; usa espera exponencial acotada con variación aleatoria| |`529`|Sobrecarga temporal|Reintenta con un máximo de intentos y tiempo total| El gateway puede tener códigos o formatos propios. Comprueba también la ruta y el model ID exacto si el modelo no está disponible. No compartas claves ni cuerpos privados en los diagnósticos. Separa la evaluación de sus efectos: repetir una clasificación no debe enviar dos correos ni emitir dos reembolsos. Si los intentos fallan, muestra el fallo o deriva el caso para revisión; no lo conviertas silenciosamente en una respuesta segura. ## Preguntas frecuentes ### ¿Es esta la documentación oficial de Jev? Es una guía de integración de OmniaKey. La [referencia de TypeSafe](https://docs.typesafe.ai/api) define el esquema directo y su [página de modelos](https://docs.typesafe.ai/models) define precios y límites. La tabla inicial distingue ambos servicios. ### ¿Puede recibir imágenes o redactar texto? Jev 1.14 acepta texto por defecto y devuelve decisiones tipadas. Convierte los archivos no textuales en texto o campos antes de enviarlos; la entrada de imágenes de 1.14 está detrás de un ajuste experimental. Para generar explicaciones, imágenes o vídeo necesitas otro modelo o paso de aplicación. ### ¿Conviene usar un alias o una versión fija? El alias facilita las pruebas iniciales. En un flujo con umbrales, evalúa una versión admitida, registra `model` y vuelve a validar los umbrales antes de cambiarla. El catálogo del gateway puede diferir del directo. ## Fuentes - [Referencia de la API](https://docs.typesafe.ai/api) - [Modelos, precios, alias y límites](https://docs.typesafe.ai/models) - [Interpretación de la confianza](https://docs.typesafe.ai/confidence) - [Limitaciones de Jev 1.13](https://docs.typesafe.ai/model-jaggedness/jev-1.13)