Guía API de Jev

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.

Elige el endpoint y la clave que le corresponde

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 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 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.

{
  "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.

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

También recibes model y usage.input_tokens / usage.output_tokens. Actualmente jev-latest resuelve a jev-1.13.0, pero un alias puede cambiar. Registra la versión que respondió al evaluar el comportamiento.

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.

{
  "model": "jev-1.13.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.

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))

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.

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 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

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 define el esquema directo y su página de modelos define precios y límites. La tabla inicial distingue ambos servicios.

¿Puede recibir imágenes o redactar texto?

Jev 1.13 acepta texto y devuelve decisiones tipadas. Convierte los archivos no textuales en texto o campos antes de enviarlos. 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
• Modelos, precios, alias y límites
• Interpretación de la confianza
• Limitaciones de Jev 1.13