Cómo usar la API de Jev

Jev expone un único endpoint. Envías un estado y un conjunto de preguntas; devuelve respuestas tipadas con probabilidades. Aquí tienes todo lo que necesitas para hacer tu primera llamada.

1. El endpoint

Cada petición es un POST a https://api.typesafe.ai/v1/systemone, autenticado con un token Bearer. Los SDK oficiales leen tu clave de la variable de entorno TYPESAFE_API_KEY.

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Customer: I was charged twice and I am furious.",
    "questions": {
      "topic": {
        "type": "choice",
        "instructions": "What is the issue about?",
        "criteria": { "billing": "money problems", "bug": "broken product" }
      },
      "urgent": {
        "type": "noul",
        "instructions": "Escalate to a human now?"
      }
    }
  }'

curl https://jevtypesafeai.com/api/v1/decide \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Customer: I was charged twice and nobody has replied for 3 days.",
    "questions": {
      "route":    { "type": "choice", "instructions": "Where should this go?",
                    "criteria": { "billing": "money", "bug": "broken", "account": "login" } },
      "urgency":  { "type": "score",  "instructions": "How urgent is this?",
                    "criteria": ["routine", "today", "urgent", "critical"] },
      "escalate": { "type": "noul",   "instructions": "Escalate to a human now?" }
    }
  }'

2. El cuerpo de la petición

Tres campos:

• model — jev-latest, o fija una versión como jev-1.13.0 si ajustas umbrales.
• state — el contexto, como cadena, objeto JSON o array de texto. Hasta ~64k tokens combinados con tus preguntas.
• questions — un mapa de nombres de pregunta a objetos de pregunta. Todas se evalúan en un solo viaje de ida y vuelta.

3. Los tres tipos de pregunta

choice — elige una opción

Da un mapa de criterios de hasta 255 opciones etiquetadas. Jev devuelve la clave ganadora, una probabilidad por opción y una confianza.

"topic": {
  "type": "choice",
  "instructions": "What is the primary issue?",
  "criteria": {
    "billing": "billing or payment problem",
    "bug": "the product is broken",
    "account": "login or access"
  }
}

score — posición en una escala

Da un array ordenado de criterios con 2–10 descripciones de nivel. Jev devuelve un score (posiblemente fraccionario) más la distribución completa.

"severity": {
  "type": "score",
  "instructions": "How urgent is this?",
  "criteria": [
    "routine",
    "handle today",
    "urgent",
    "critical, about to churn"
  ]
}

noul — sí/no calibrado

Sin criterios — solo instrucciones. Jev devuelve noul, una probabilidad de 0 a 1.

"escalate": {
  "type": "noul",
  "instructions": "Escalate to a human immediately?"
}

4. La respuesta

Recibes de vuelta el modelo resuelto, un mapa de answers y el uso de tokens:

{
  "model": "jev-1.13.0",
  "answers": {
    "topic":    { "type": "choice", "choice": "billing",
                  "confidence": 1.0,
                  "probabilities": { "billing": 1.0, "bug": 0.0, "account": 0.0 } },
    "severity": { "type": "score", "score": 3.0, "confidence": 1.0,
                  "legend": { "0": "routine", "3": "critical, about to churn" },
                  "probabilities": { "0": 0.0, "3": 1.0 } },
    "escalate": { "type": "noul", "noul": 0.8 }
  },
  "usage": { "input_tokens": 434, "output_tokens": 75 }
}

Como los tipos están fijos, puedes ramificar sobre los resultados con código plano — if (answers.escalate.noul > 0.7) — sin parseo, sin regex y sin riesgo de una respuesta malformada.

5. Límites y buenas prácticas

• Límites de frecuencia: 250,000 tokens/second y 1,200 requests/minute.
• Contexto: hasta 64k tokens para el estado + todas las preguntas; 32k para el estado + una sola pregunta, la más larga.
• Fija versiones en producción si tus umbrales importan — jev-latest puede cambiar de comportamiento.
• Agrupa las preguntas en una sola llamada en lugar de muchas; se ejecutan en paralelo y comparten el coste del estado.
• Usa la confianza para gestionar automáticamente los casos fáciles y enrutar solo los inciertos a una persona o a un modelo más grande.

¿Quieres verlo antes de escribir código? Cada ejemplo de esta página se ejecuta en vivo en el playground. Para claves oficiales y documentación completa, consulta docs.typesafe.ai.