Jev API Docs

Endpoint

Envía POST a /api/v1/decisions en este host. No hay ruta de chat-completions ni respuesta en streaming. GET /api/v1/models lista el id del modelo. El endpoint compatible POST /v1/systemone se cubre más abajo.

POST https://jev-api.org/api/v1/decisions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Autenticación

Pon la clave del panel en Authorization: Bearer. Una clave ausente o rechazada devuelve 401. El playground crea una clave de la cuenta al ejecutar.

Inicio rápido

Pon JEV_API_KEY a una clave de tu panel y envía la solicitud de abajo.

curl https://jev-api.org/api/v1/decisions \
  -H "Authorization: Bearer $JEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "jev-1.13",
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "What is the overall sentiment of this message?",
      "criteria": {
        "positive": "Satisfied or thankful overall.",
        "mixed": "Both satisfied and unhappy.",
        "negative": "Unhappy overall."
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "Should a person reply to this message?"
    }
  }
}'

Usar con herramientas de programación con IA

Copia un prompt con el contrato de solicitud completo y pégalo en Cursor, Claude Code o ChatGPT junto con tu tarea. La misma referencia está en /llms.txt.

Cuerpo de la solicitud

model es jev-1.13 o jev-latest. state es una cadena, objeto JSON o array de texto, hasta 60,000 caracteres. questions es un mapa de 1 a 6 ids snake_case. El id es solo la etiqueta bajo la que vuelve tu respuesta, no una pregunta. La pregunta real va en instructions, como texto de 1 a 2,000 caracteres.

{
  "model": "jev-1.13",
  "state": "Thanks for the refund. Still annoyed it took three emails.",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "What is the overall sentiment of this message?",
      "criteria": {
        "positive": "Satisfied or thankful overall.",
        "mixed": "Both satisfied and unhappy.",
        "negative": "Unhappy overall."
      }
    },
    "needs_follow_up": {
      "type": "noul",
      "instructions": "Should a person reply to this message?"
    }
  }
}

Tipos de pregunta

Noul

type noul solo necesita instructions. El campo noul es la probabilidad de 0 a 1 de que la afirmación sea cierta. No hay un campo confidence aparte. Si envías criteria en una pregunta noul, este endpoint la ignora.

Choice

type choice necesita instructions y criteria: un objeto de 2 a 8 ids snake_case mapeados a descripciones de hasta 300 caracteres. La respuesta incluye choice, probabilities de cada opción y confidence.

Score

type score necesita instructions y criteria como un array ordenado de 2 a 10 niveles, el más bajo primero. La respuesta incluye score, legend, probabilities y confidence.

Respuesta

Un cuerpo correcto tiene model, answers con tus ids de pregunta, usage con input_tokens y output_tokens, y credits_used. model informa jev-1.13 aunque envíes jev-latest. Abajo hay una respuesta de ejemplo a la solicitud del inicio rápido, con usage omitido.

{
  "model": "jev-1.13",
  "answers": {
    "sentiment": {
      "type": "choice",
      "choice": "mixed",
      "probabilities": { "mixed": 0.79, "negative": 0.2, "positive": 0.01 },
      "confidence": 0.61
    },
    "needs_follow_up": { "type": "noul", "noul": 0.83 }
  },
  "credits_used": 1
}

Cómo leer probabilidades y confidence

Noul es la probabilidad de que la afirmación en instructions sea cierta. Choice y Score devuelven una probabilidad por opción o nivel, más confidence.

El segundo es la señal para pasar a una persona. Cuando confidence es bajo o dos opciones están cerca, envía el caso a una persona o haz una pregunta más concreta. No bajes el umbral antes de mirar esos casos ajustados.

Límites

Diferencias con la API de TypeSafe

TypeSafe AI sirve Jev en POST https://api.typesafe.ai/v1/systemone con una clave de TypeSafe y factura por token de entrada. El POST /v1/systemone de este sitio acepta el mismo cuerpo tal cual; el más simple POST /api/v1/decisions difiere en lo siguiente:

• Ruta y clave: POST /api/v1/decisions en jev-api.org, con una clave del panel de este sitio. Las claves de TypeSafe no funcionan aquí, y las de este sitio no funcionan en TypeSafe.
• Id del modelo: en /api/v1/decisions envía jev-1.13 o jev-latest; un id versionado como jev-1.13.0 devuelve 422. /v1/systemone acepta jev-latest, jev-preview, jev-1.13, jev-1.13.0 y typesafe/jev-1.13.
• Límites: /api/v1/decisions permite de 1 a 6 preguntas por llamada y de 2 a 8 opciones de Choice. /v1/systemone acepta los rangos completos de TypeSafe — hasta 256 preguntas y 255 opciones de Choice.
• Campos: en /api/v1/decisions instructions debe ser texto y cada opción de Choice necesita descripción. /v1/systemone también acepta instructions como objeto o array y descripciones de opción null.
• Facturación: 1 crédito por llamada con éxito, sea cual sea el número de tokens.

Endpoint compatible con el SDK de TypeSafe

POST /v1/systemone en este host acepta el cuerpo de TypeSafe tal cual — model, state y questions — y devuelve la forma de respuesta de TypeSafe: model, answers, usage. Apunta un cliente compatible con TypeSafe a la base URL https://jev-api.org o llama directamente a https://jev-api.org/v1/systemone. GET /v1/models lista los modelos servidos sin clave.

POST https://jev-api.org/v1/systemone
GET  https://jev-api.org/v1/models

Ids de modelo aceptados: jev-latest, jev-preview, jev-1.13, jev-1.13.0, typesafe/jev-1.13. Esta ruta acepta los rangos más amplios de TypeSafe — de 1 a 256 preguntas, de 2 a 255 opciones de Choice, de 2 a 10 niveles de Score, instructions como objeto o array — y los límites de 64k tokens por petición y 32k para el estado más la pregunta más larga. La facturación es la misma: 1 crédito por llamada correcta.

Python

from typesafe_sdk import Noul, TypeSafeClient

with TypeSafeClient(api_key="YOUR_JEV_API_KEY", base_url="https://jev-api.org") as client:
    response = client.system_one(
        state="The invoice total does not match the quote.",
        questions={"is_billing": Noul(instructions="Is this about billing?")},
    )

print(response.answers["is_billing"])

JavaScript

const res = await fetch('https://jev-api.org/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.JEV_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'jev-latest',
    state: 'The invoice total does not match the quote.',
    questions: { is_billing: { type: 'noul', instructions: 'Is this about billing?' } },
  }),
})
const { answers } = await res.json()

Guía de Jev con Python·Modelos Jev

Errores

• 401 — clave ausente o rechazada.
• 402 — la clave es válida y el saldo no cubre la llamada. Un fallo upstream no usa un crédito.
• 422 — el cuerpo no pasó la validación. El mensaje nombra el campo.
• 429 — el servicio de decisión está limitado. Reintenta más tarde.
• 502 — el servicio no devolvió respuestas. No se usa un crédito.