¿Cómo obtener una clave API de Jev (TypeSafe AI)?

Jev es el modelo de decisión de TypeSafe AI. Le envías un estado y un conjunto de preguntas tipadas, y responde con probabilidades en lugar de prosa. Esta guía cubre la clave API de Jev y tu primera solicitud; para entender qué es Jev y por qué devuelve números en lugar de texto, lee primero qué es Jev. Para ser claros, ya que los resultados de búsqueda son confusos: este es Jev el modelo de TypeSafe AI, no FaZe Jev el YouTuber y no la vacuna JEV.

Una clave API de Jev funciona como cualquier otro token de portador, así que si eres nuevo en el patrón, qué es una clave API cubre los conceptos básicos. El acceso directo a la API está en acceso anticipado, así que el primer paso es salir de la lista de espera. Después de eso, crearás la clave, aprenderás la forma de la solicitud, llamarás al endpoint con curl y el SDK de Python, leerás los campos de probabilidad y conectarás la solicitud a Apidog con aserciones sobre esas probabilidades. Si no puedes esperar, el mismo modelo está disponible en Vercel AI Gateway sin lista de espera; la sección de preguntas frecuentes cubre esa ruta.

Paso 1: obtén acceso anticipado, luego crea la clave

Jev está en acceso anticipado al momento de escribir esto. La publicación de lanzamiento de TypeSafe dice que están “sacando a los desarrolladores de la lista de espera lo más rápido posible”, así que únete a la lista de espera en typesafe.ai y espera la invitación a la consola; aún no hay un registro de autoservicio. Una vez que tu cuenta de consola esté activa, ve a console.typesafe.ai/settings/keys y crea una clave. Cópiala una vez y trátala como una contraseña.

Expórtala como una variable de entorno en lugar de pegarla en el código:

export TYPESAFE_API_KEY="ts_..."

Los ejemplos oficiales de curl y el SDK de Python leen TYPESAFE_API_KEY del entorno, por lo que una variable cubre cada ejemplo a continuación. Si una clave llega a un commit, rótala en la consola y ejecuta una verificación de fuga de clave API en todo el repositorio.

Paso 2: comprende la forma de la solicitud

Cada llamada a Jev es una única POST https://api.typesafe.ai/v1/systemone con tres campos en el cuerpo, documentados en la referencia de la API de TypeSafe:

Cada pregunta es uno de tres primitivos:

La respuesta también incluye model y usage.input_tokens / usage.output_tokens. Preguntas de diferentes tipos pueden compartir un mismo estado y regresar en un solo viaje de ida y vuelta.

Paso 3: haz la primera solicitud con curl

Esta solicitud ejecuta los tres primitivos contra un ticket de soporte:

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Mi tarjeta fue cargada dos veces por un pedido y nadie ha respondido en tres días.",
    "questions": {
      "needs_review": {
        "type": "noul",
        "instructions": "¿Este ticket necesita un agente humano?",
        "criteria": {
          "true": "dinero, legal o una queja sin respuesta",
          "false": "una pregunta rutinaria que un bot puede cerrar"
        }
      },
      "route": {
        "type": "choice",
        "instructions": "Dirige este ticket a un equipo.",
        "criteria": {
          "billing": "problemas de pago o cobro",
          "shipping": "problemas de entrega",
          "technical": "errores de aplicación"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "¿Qué tan urgente es este ticket?",
        "criteria": ["baja", "media", "alta"]
      }
    }
  }'

Una respuesta se ve así (los valores son ilustrativos):

{
  "model": "jev-1.13.0",
  "answers": {
    "needs_review": { "type": "noul", "noul": 0.97 },
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.98,
      "probabilities": { "billing": 0.98, "shipping": 0.01, "technical": 0.01 }
    },
    "urgency": {
      "type": "score",
      "score": 1.6,
      "confidence": 0.62,
      "legend": { "0": "baja", "1": "media", "2": "alta" },
      "probabilities": { "0": 0.02, "1": 0.36, "2": 0.62 }
    }
  },
  "usage": { "input_tokens": 190, "output_tokens": 0 }
}

Paso 4: lee los campos de probabilidad

Lee los números con precisión:

• noul es la probabilidad de "sí". 0.97 significa que Jev está 97% seguro de que este ticket necesita un humano.
• choice es la opción de mayor probabilidad, probabilities enumera cada opción, y confidence indica cuán decisiva fue la elección. Una ruta de 0.98 es segura para automatizar; una ruta de 0.51 con 0.47 en el segundo puesto es un volado.
• score es la posición ponderada por probabilidad a través de los niveles ordenados, por lo que 1.6 se encuentra entre "media" (1) y "alta" (2). legend mapea cada índice a su etiqueta, y probabilities muestra la distribución completa.

Debido a que la salida es una distribución, no una etiqueta, tú estableces el umbral, no el modelo. Por eso las aserciones en el Paso 6 prueban números.

Paso 5: la misma llamada con el SDK de Python

Instala el SDK; el cliente toma TYPESAFE_API_KEY del entorno:

pip install typesafe-sdk

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="Mi tarjeta fue cargada dos veces por un pedido y nadie ha respondido en tres días.",
        questions={
            "needs_review": Noul(
                instructions="¿Este ticket necesita un agente humano?",
                criteria={"true": "dinero, legal o una queja sin respuesta",
                          "false": "una pregunta rutinaria que un bot puede cerrar"},
            ),
            "route": Choice(
                instructions="Dirige este ticket a un equipo.",
                criteria={"billing": "problemas de pago o cobro",
                          "shipping": "problemas de entrega",
                          "technical": "errores de aplicación"},
            ),
            "urgency": Score(
                instructions="¿Qué tan urgente es este ticket?",
                criteria=["baja", "media", "alta"],
            ),
        },
    )

print(response.nouls["needs_review"].noul)
print(response.choices["route"].choice, response.choices["route"].probabilities)
print(response.scores["urgency"].score)

Las respuestas se agrupan por tipo en el objeto de respuesta (nouls, choices, scores). Hay un SDK de JavaScript con la misma forma, y si ya estás en Vercel AI Gateway, experimental_evaluate del AI SDK 7 llama al modelo como typesafe-ai/jev, con una diferencia: el tipo de pregunta booleana devuelve un campo probability en lugar de noul.

Paso 6: almacena y prueba la clave API de Jev en Apidog

Curl prueba que la clave funciona una vez. Apidog hace que la solicitud sea repetible, asertiva y simulable para todo el equipo.

Almacena la clave como una variable secreta. Crea un entorno llamado TypeSafe y añade TYPESAFE_API_KEY como secreto para que su valor permanezca enmascarado en la interfaz de usuario y fuera de las exportaciones; Entornos de Apidog y variables secretas explica la configuración. Establece la autenticación de la solicitud a Bearer Token con {{TYPESAFE_API_KEY}} como valor.

Crea la solicitud POST. Añade un POST a https://api.typesafe.ai/v1/systemone, pega el cuerpo JSON del Paso 3 y envíalo. El panel de respuesta muestra el árbol de respuestas, para que puedas verificar las probabilidades antes de escribir una aserción.

Realiza aserciones sobre probabilidades, no sobre prosa. En el constructor visual de aserciones, apunta las expresiones JSONPath a los campos que te interesan:

• $.answers.needs_review.noul es mayor que 0.9
• $.answers.route.choice es igual a billing
• $.answers.route.probabilities.billing es mayor que 0.8
• $.answers.urgency.score es mayor o igual a 1
• $.usage.input_tokens es menor que 1000

Si prefieres scripts, el post-procesador acepta la API familiar de pm:

const body = pm.response.json();
pm.test("ticket marcado para un humano", () => {
  pm.expect(body.answers.needs_review.noul).to.be.above(0.9);
});
pm.test("dirigido a facturación", () => {
  pm.expect(body.answers.route.choice).to.eql("billing");
});

Guárdalo como un escenario de prueba. Coloca la solicitud en un escenario de prueba con un pequeño CSV de tickets y rutas esperadas, y ejecútalo con cada cambio en tus instrucciones o criterios. Las ediciones de prompts son cambios de código; un escenario de diez filas detecta la edición que silenciosamente mueve un 0.95 a un 0.6. El mismo escenario se ejecuta en CI a través de la CLI de Apidog, por lo que una regresión bloquea la fusión.

Simula la forma de respuesta declarada. Define el esquema de respuesta en el endpoint (los tres objetos de respuesta más `usage`), y el simulador inteligente de Apidog sirve probabilidades falsas realistas de inmediato. El frontend puede construir la insignia de "necesita revisión" y la interfaz de usuario de enrutamiento contra el simulador antes de que el backend se lance, y luego intercambiar la URL del simulador por el endpoint real con un solo cambio de entorno.

Para la planificación de puestos: el plan Gratuito de Apidog incluye 4 usuarios, y los niveles de pago son por puesto.

Umbrales en el código

Una vez que las aserciones pasan, los mismos números impulsan la lógica de producción. Mantén los umbrales en un solo lugar y nómbralos:

REVIEW_THRESHOLD = 0.9
AUTO_ROUTE_CONFIDENCE = 0.85

needs_review = response.nouls["needs_review"].noul >= REVIEW_THRESHOLD
route = response.choices["route"]

if route.confidence >= AUTO_ROUTE_CONFIDENCE and not needs_review:
    assign(ticket, team=route.choice) # Asigna el ticket a un equipo
else:
    queue_for_human(ticket, suggested=route.choice) # Poner en cola para revisión humana

Registra el mapa completo de `probabilities` con cada decisión para que puedas ajustar los umbrales a partir de datos reales más adelante, y haz que la revisión humana sea la opción predeterminada cuando la confianza sea baja; el modelo te está diciendo que no está seguro.

Límites, precios y modelos

Directamente de la página de modelos de TypeSafe:

A ese precio, un millón de tickets cortos cuestan menos de $10. TypeSafe también afirma que Jev no está entrenado con solicitudes o respuestas de clientes.

Errores comunes y cómo solucionarlos

Un 422 es el error que más encontrarás al iterar; el esquema del endpoint del Paso 6 los detecta la mayoría antes de que la solicitud salga de tu máquina.

Preguntas frecuentes

¿Hay un nivel gratuito para la API de Jev? La documentación pública enumera precios por token y no describe un nivel gratuito ni créditos de inicio, y el acceso en sí está en lista de espera por ahora. Revisa la consola una vez que recibas tu invitación para la oferta actual, y trata cualquier cifra que veas en otro lugar como no oficial.

¿Puedo obtener varias respuestas de una sola solicitud? Sí. questions es un mapa, por lo que un noul, una opción y una puntuación pueden ejecutarse contra un mismo estado en una sola llamada. Es más barato que tres solicitudes y mantiene las respuestas consistentes porque comparten una misma entrada.

¿En qué se diferencia esto de las salidas estructuradas en un modelo de chat? Las salidas estructuradas obligan a un modelo de lenguaje a emitir JSON válido, pero los valores internos siguen siendo tokens generados, y un campo de "confianza" es texto que el modelo escribió sobre sí mismo. Jev devuelve probabilidades medidas como la salida nativa, por lo que puedes afirmar noul > 0.9 y confiar en la comparación.

¿Necesito el SDK de TypeSafe si estoy en Vercel? No. El SDK de Vercel AI expone Jev a través de experimental_evaluate con typesafe-ai/jev como ID del modelo. Te autenticarás con tu clave de AI Gateway en lugar de una clave de TypeSafe, y la respuesta booleana regresa como probability.

Próximos pasos

Ahora tienes una clave API de Jev, una solicitud funcional en curl y Python, y una comprensión clara de noul, choice y score. Introduce la solicitud en Apidog, añade las aserciones de probabilidad y guarda el escenario de prueba para que las ediciones de los prompts se prueben como código. Descarga Apidog para seguir los pasos.