Utiliser l’API Jev

L’API Jev évalue un texte à partir de questions définies par votre application. Vous envoyez state, model et une table questions, puis lisez les décisions typées dans answers, sous les mêmes identifiants. Il ne s’agit pas d’une réponse de chat dont il faudrait extraire les étiquettes après coup.

Ce guide concerne l’intégration. Pour les usages, les prix et les limites du modèle, consultez notre présentation de Jev.

Choisir le point d’accès et la bonne clé API

Les deux routes utilisent Authorization: Bearer ... et le corps natif de Jev. N’envoyez pas la clé d’un service à l’autre. Le point d’accès OmniaKey n’est pas /v1/chat/completions : remplacer state par messages change le contrat.

Créez une clé aux droits limités, vérifiez la route Jev disponible et définissez OMNIAKEY_API_KEY dans votre environnement local. Ne placez pas la clé dans le navigateur, Git ou une capture. Le guide de démarrage API (en anglais) détaille la configuration générale.

Construire une requête JSON complète

Enregistrez ce contenu dans jev-request.json. Une même demande classe un message de support par service, frustration et urgence. L’exemple reste en anglais, langue actuellement la plus performante selon TypeSafe ; évaluez le français sur des données représentatives de votre usage.

{
  "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?"
    }
  }
}

Les identifiants relient questions et réponses. TypeSafe indique qu’ils ne participent pas à l’inférence : décrivez la tâche dans instructions, pas seulement dans le nom de la clé. state accepte aussi un objet ou un tableau JSON contenant du texte, par exemple un ticket aux champs séparés.

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

Pour TypeSafe en direct, remplacez l’URL par https://api.typesafe.ai/v1/systemone et utilisez $TYPESAFE_API_KEY. Conservez le schéma JSON et vérifiez les noms de modèles acceptés par ce compte.

Lire les réponses Choice, Score et Noul

La réponse contient aussi model et usage.input_tokens / usage.output_tokens. À la date de vérification, jev-latest pointe vers jev-1.13.0. Un alias peut évoluer : enregistrez la version réellement utilisée.

Sur un barème de trois niveaux, 1.05 se situe juste au-dessus du niveau 1 ; ce n’est pas une note sur 100. Utilisez legend. Un Noul de 0.8 n’autorise pas à lui seul un remboursement. Réglez les seuils sur des exemples annotés. confidence est calculé à partir de la distribution et ne garantit pas une décision correcte.

Cette réponse complète est un exemple illustratif, pas le résultat d’un appel réel à l’API. Les valeurs et les nombres de tokens servent à expliquer la structure ; les résultats réels peuvent varier.

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

Appeler Jev avec Python ou Node.js

Ces exemples relisent jev-request.json et font une seule requête. Ils affichent les réponses natives sans supposer un champ OpenAI choices. Ajoutez une politique de reprises bornées pour la production.

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

Utilisez Python 3 ou une version de Node.js comprenant fetch et AbortSignal.timeout. Ce sont des exemples HTTP, pas une affirmation de compatibilité native avec le SDK OpenAI. TypeSafe présente ses propres SDK dans la documentation officielle.

Contexte, quotas et facturation

Deux contraintes s’appliquent simultanément : 64K tokens pour toute la requête, et 32K pour state plus la question individuelle la plus longue. Retirez les informations inutiles et ne regroupez que les questions qui ont réellement besoin du même état.

TypeSafe annonce 250,000 tokens par seconde et 1,200 requêtes par minute, avec des limites susceptibles d’évoluer pendant l’accès initial. Ce sont des quotas de compte, ni une mesure de vitesse par requête ni une promesse pour OmniaKey. La passerelle peut ajouter ses propres limites.

Le tarif direct vérifié est de $0.042 par million de tokens d’entrée, avec une sortie gratuite. Le nombre de tokens de sortie reste présent dans la réponse. Cela ne rend pas toute l’API gratuite et ne prouve pas que la passerelle facture selon la même unité. Consultez sa cotation et vos relevés ; la présentation du modèle explique les prix et les limites.

Dans le catalogue actuel d’OmniaKey, Jev est facturé par requête. Vérifiez le prix en vigueur et les relevés du tableau de bord avant d’estimer le coût de la passerelle.

Traiter les erreurs et les reprises

Ces statuts décrivent l’API directe. Une passerelle peut avoir ses propres erreurs d’authentification, de validation ou de fournisseur. Vérifiez aussi l’URL et l’identifiant exact du modèle. Ne partagez ni clés ni corps privés dans les diagnostics.

Séparez l’évaluation de ses effets métier : relancer une classification ne doit pas envoyer deux e-mails ou rembourser deux fois. Après plusieurs échecs, rendez l’erreur visible ou demandez une vérification ; ne la transformez pas silencieusement en décision certaine.

Questions fréquentes

Est-ce la documentation officielle de Jev ?

C’est un guide d’intégration OmniaKey. La référence TypeSafe définit le contrat direct et la page des modèles les prix et quotas. Le tableau des points d’accès distingue les services.

Jev accepte-t-il les images ou génère-t-il du texte ?

Jev 1.13 accepte du texte et renvoie les décisions typées décrites ici. Convertissez les contenus non textuels en texte ou en champs structurés. La rédaction d’explications ou la génération d’images et de vidéos demandent un autre modèle ou une autre étape.

Faut-il utiliser un alias ou une version fixe ?

Un alias simplifie l’exploration. Pour un processus à seuils, évaluez une version prise en charge, conservez le model retourné et revalidez les seuils avant de changer. Les modèles accessibles peuvent différer selon la route.

Sources

• Référence de l’API TypeSafe
• Modèles, prix, alias et quotas
• Interpréter la confiance
• Limites de Jev 1.13