Tutorial de la API de Jev AI: crea tu primera decisión estructurada con Choice, Score y Noul

Si ya has probado el modelo en el Playground de Jev AI, el siguiente paso suele ser conectar una decisión real con un flujo de trabajo en el servidor: recibir un ticket o mensaje, definir las preguntas que necesita tu producto, leer probabilidades y confianza, y dejar que el código decida si debe enrutarlo, ponerlo en una cola o solicitar una revisión humana.

La API de Jev AI no está pensada principalmente para enviar una petición de chat. Su modelo central utiliza tres entradas claras: State, Model y Questions. State describe el contexto, Questions define las evaluaciones y la respuesta devuelve resultados tipados mediante el ID de cada pregunta. Así puedes integrar el juicio de la IA en funciones, colas y flujos de agentes existentes sin añadir otra interfaz de chat.

Este tutorial explica la estructura de la petición, cómo elegir entre Choice, Score y Noul, una petición mínima con curl, el tratamiento de la respuesta, el flujo de control, los límites de error y una lista de comprobación para producción.

Objetivo del tutorial: crear una evaluación de bajo riesgo para un ticket de soporte y permitir que el servidor decida si lo enruta automáticamente o solicita una revisión humana.

Tabla de contenidos

• Entender el modelo de petición de Jev
• State: proporcionar contexto
• Questions: elegir Choice, Score o Noul
• Enviar tu primera petición a la API de Jev
• Leer y procesar la respuesta
• Conectar el resultado con la lógica de la aplicación
• Lista de comprobación para producción
• Preguntas frecuentes

Entender el modelo de petición de Jev

Imagen: State aporta el contexto, Questions describen la evaluación y el resultado estructurado vuelve a tu servicio.

La idea básica se puede expresar así:

state + model + questions
            ↓
typed answers + probabilities + confidence
            ↓
your application logic

La documentación actual del sitio web indica POST https://thejevai.com/v1/systemone como endpoint de producción. La petición tiene tres campos principales:

• state: una cadena, un objeto JSON o un array de textos;
• model: el nombre del modelo, como typesafe/jev-1.13;
• questions: preguntas tipadas con IDs estables de tu lógica de negocio como claves.

Jev realiza la evaluación. Tu aplicación sigue siendo responsable de la autenticación, la limpieza de entradas, los umbrales, los reintentos, el registro y la acción final. Para conocer el modelo general del producto, consulta la introducción a Jev AI.

State: proporcionar contexto

Usa una cadena para un caso sencillo

Si todas las evaluaciones se refieren a un solo mensaje, una cadena es el State más sencillo:

{
  "state": "The customer has tried to connect Stripe for three days."
}

Funciona bien con mensajes de soporte, alertas, descripciones de formularios, comentarios de usuarios y tickets breves.

Usa un objeto JSON para contexto estructurado

Si una evaluación necesita considerar un ticket, un pedido y una política a la vez, usa un objeto:

{
  "ticket": {
    "text": "The customer has tried to connect Stripe for three days.",
    "channel": "email"
  },
  "customer": {
    "plan": "pro",
    "days_open": 3
  },
  "policy": {
    "same_day_escalation": true
  }
}

Un objeto pone los datos compartidos a disposición de todas las preguntas, pero eso no significa que debas enviar todos los campos del sistema. Proporciona solo el contexto necesario para la evaluación y elimina secretos, datos de pago e información personal innecesaria antes de que la petición salga de tu servicio.

Usa un array para textos relacionados

Puedes representar varios mensajes, fragmentos recuperados o resúmenes de conversaciones como un array de textos. Cada elemento debe ser relevante para la evaluación actual; no mezcles material ajeno en State esperando que el modelo lo ignore perfectamente.

La documentación actual del sitio enumera textos, objetos JSON y arrays de textos como entradas compatibles. Por ahora, las imágenes, el audio y el vídeo no son entradas directas. Procésalos antes con transcripción, OCR u otro servicio.

Questions: elegir Choice, Score o Noul

Imagen: el tipo de pregunta determina la forma de la respuesta y cómo se incorpora el resultado al flujo de control.

Tipo de pregunta	Úsalo para	Resultado principal	Acción habitual
Choice	Elegir una opción de un conjunto	choice, probabilities, confidence	Enrutamiento, clasificación, selección de modelo
Score	Evaluar según una escala ordenada	score, legend, probabilities, confidence	Clasificación, prioridad, SLA
Noul	Determinar si una afirmación es verdadera	noul (probabilidad de «sí»)	Bloqueo, confirmación, escalado

Choice: clasificación y enrutamiento

Usa Choice cuando puedas enumerar las respuestas: equipos de soporte, categorías de contenido, tipos de tarea y niveles de modelo. Incluye other o none-of-the-above para los casos desconocidos en lugar de forzar una coincidencia incorrecta.

Score: evaluación ordenada

Usa Score para la gravedad, la satisfacción, la urgencia y los niveles de riesgo. Los niveles deben estar ordenados de menor a mayor y tener descripciones concretas. No te limites a definir «bajo, medio, alto»: especifica qué acción de negocio debe activar cada nivel.

Noul: una sola evaluación de sí o no

Usa Noul cuando la pregunta se pueda reformular como «¿Es verdadera esta afirmación?». Por ejemplo: «¿El cliente está solicitando explícitamente un reembolso?» o «¿Esta llamada a una herramienta requiere confirmación humana?». Noul devuelve una probabilidad de respuesta afirmativa y no debe confundirse con un campo de confianza independiente.

La documentación de TypeSafe destaca la importancia de las preguntas atómicas. En vez de hacer una sola pregunta para determinar el departamento, la prioridad y el riesgo, sepáralas y combina los resultados en el código.

Enviar tu primera petición a la API de Jev

Imagen: valida una petición pequeña y bien delimitada antes de ampliarla a varias preguntas.

Prepara una clave de API

Guarda la clave de API en una variable de entorno del servidor:

export JEV_API_KEY="your-server-side-key"

Nunca incluyas la clave real en código del navegador, un paquete para el cliente, un artículo público ni un repositorio Git. Para conocer las recomendaciones actuales sobre la gestión de claves, consulta la documentación de la API de Jev AI.

Envía una petición Noul mínima

La siguiente petición sigue la estructura de campos que muestra actualmente la documentación oficial del sitio web:

curl -X POST https://thejevai.com/v1/systemone \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "A customer has tried to connect Stripe for three days.",
    "questions": {
      "urgent": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }'

Usa el Playground para inspeccionar una petición

Si no tienes claro el formato JSON completo de Choice o Score, define una pregunta en el Playground, ejecútala e inspecciona la vista previa de la petición API que proporciona la página. Es más seguro que adivinar los nombres de campo a partir de un ejemplo antiguo.

Leer y procesar la respuesta

Imagen: valida la respuesta y el umbral antes de enviarla a una automatización o revisión.

Lee las respuestas por ID de pregunta

La respuesta utiliza los IDs de las preguntas que enviaste. Conceptualmente, podría tener este aspecto:

{
  "answers": {
    "urgent": {
      "noul": 0.87
    }
  },
  "usage": {
    "input_tokens": 42,
    "output_tokens": 0
  },
  "elapsedMs": 214
}

Esto es una ilustración de la respuesta, no un esquema completo de la API. Consulta la referencia oficial de la API para ver los campos, errores y versiones de modelo actuales.

Trata la probabilidad como una señal, no como un veredicto

Define distintos umbrales según el nivel de riesgo:

• Enrutamiento de tickets de bajo riesgo: urgent > 0.8 puede enviarse a una cola automática.
• Acciones de riesgo medio: 0.6–0.8 puede activar un muestreo o una segunda evaluación.
• Acciones de alto riesgo: incluso una probabilidad alta debe superar la autorización, las reglas estrictas y la confirmación humana.

Los umbrales forman parte de tu política de negocio; no son una respuesta predeterminada de Jev. Calíbralos con datos históricos y contraejemplos.

Gestiona errores y tiempos de espera

Un cliente de producción debe gestionar respuestas distintas de 2xx, tiempos de espera, campos ausentes, opciones desconocidas, cambios de versión del modelo y envíos duplicados. Los reintentos necesitan una estrategia de idempotencia: un fallo de red no debe repetir un pago, un borrado ni un cambio de permisos.

Conectar el resultado con la lógica de la aplicación

Ejemplo: flujo de prioridad para tickets de soporte

result = jev.system_one(
    model="typesafe/jev-1.13",
    state=ticket,
    questions={
        "needs_human": {
            "type": "noul",
            "instructions": "Does this ticket require a human review?"
        }
    },
)

if result.answers["needs_human"].noul >= 0.85:
    queue_for_review(ticket)
else:
    route_automatically(ticket)

El ejemplo ilustra el flujo de control. Para conocer los campos exactos de los SDK de Python y JavaScript o de REST, utiliza la documentación oficial actual y la petición exportada desde el Playground.

Diseña intencionadamente las peticiones con varias preguntas

Un mismo State puede admitir varias preguntas:

• department: Choice para elegir el equipo responsable;
• urgency: Score para determinar la prioridad;
• needs_human: Noul para decidir si hace falta una revisión.

Cada pregunta debe describir una sola evaluación. La aplicación combina los resultados para realizar acciones, por lo que puedes cambiar una política de enrutamiento sin reescribir la pregunta sobre urgencia o revisión.

Lista de comprobación para producción

Antes de publicar, confirma que:

1. La clave de API solo existe en secretos del servidor o en un gestor de variables de entorno.
2. State tiene límites de longitud, controles para datos sensibles y verificaciones de permisos.
3. Cada pregunta tiene un ID estable, un espacio de respuestas definido e instrucciones claras.
4. El cliente valida el estado HTTP y la estructura de la respuesta.
5. Los umbrales de probabilidad varían según el riesgo en vez de usar un único valor global.
6. Las acciones de gran impacto conservan reglas estrictas, autorización y revisión humana.
7. El sistema registra la versión del modelo, la definición de la pregunta, un resumen de la entrada y la acción final.
8. Los tiempos de espera, los reintentos, las alternativas y las vías de intervención humana están definidos.
9. Los conjuntos de evaluación incluyen chino, inglés, términos especializados y casos límite.
10. Los detalles de uso y del plan se verifican en la página de precios de Jev AI y en la documentación actual de la API.

Para conocer la arquitectura y elegir modelos, continúa con Jev AI frente a los LLM. Para obtener información sobre el enrutamiento de agentes y las medidas de seguridad, lee Guardarraíles de Jev AI para agentes.

Preguntas frecuentes

¿La API de Jev AI es un endpoint de chat?

No. Acepta State y preguntas tipadas, y devuelve respuestas estructuradas que una aplicación puede leer. Puede actuar como nodo de evaluación dentro de un sistema de chat o un agente, pero no está diseñada para generar párrafos conversacionales.

¿Una petición puede contener varias preguntas?

Sí. La documentación del sitio web y de TypeSafe describe la evaluación de varias preguntas sobre el mismo State. Mantén cada pregunta independiente y bien delimitada, y asígnale un ID estable.

¿El valor de Noul equivale a la confianza?

No. Noul es la probabilidad de que la respuesta sea sí. Choice y Score devuelven sus propios campos de probabilidad y confianza. Consulta siempre la documentación actual de la API para conocer la estructura exacta de la respuesta.

¿Jev admite imágenes?

La documentación actual del sitio web enumera textos, objetos JSON y arrays de textos como entradas de State. Por ahora, las imágenes, el audio y el vídeo no son entradas directas. Procésalos primero con OCR, transcripción u otro modelo.

¿Cómo sé si la API encaja en mi producto?

Empieza por una decisión medible y de bajo riesgo cuyo espacio de respuestas esté claro. Valídala en el Playground y después prueba el comportamiento del servidor con datos históricos y casos límite.

Conclusión

Lo importante al integrar Jev AI no es realizar una llamada al modelo, sino separar State, preguntas, resultados y acciones. State aporta los hechos, Choice/Score/Noul proporciona la evaluación, las probabilidades muestran la incertidumbre y el código de la aplicación controla la decisión final.

Una vez documentada, probada y supervisada esta cadena, Jev AI puede pasar de ser una demostración en el Playground a convertirse en un componente de decisión mantenible dentro de tu producto.

Fecha de investigación: 2026-09-20

Fuentes primarias: Sitio web de Jev AI, Documentación de Jev AI, Playground de Jev AI, Introducción de TypeSafe