# Utiliser l’API Jev

> Intégrez l’API Jev avec curl, Python et Node.js. Comprenez Choice, Score, Noul, les réponses JSON, les limites de contexte, l’authentification et les reprises.

- Canonical HTML: https://omniakey.com/fr/blog/jev-api-guide
- Markdown: https://omniakey.com/fr/blog/jev-api-guide.md
- Published: 2026-09-28 (updated 2026-10-24)
- Author: Kiki, COO at OmniaKey
- Language: fr
- Category: API setup
- Reading time: 11 min
- All posts: https://omniakey.com/blog/llms.txt

---

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 API Jev concerne l’intégration. Pour les usages, les prix et les limites du modèle, consultez notre [présentation de Jev](https://omniakey.com/fr/blog/jev-model-explained).

> **Vérifié le 24 octobre 2026.** Le contrat provient de la documentation TypeSafe ; la route de la passerelle a été rapprochée de l’implémentation OmniaKey. Les exemples ont été contrôlés hors ligne, sans nouveau test payant de performance. Les tarifs et quotas directs ne s’appliquent pas automatiquement à une passerelle.

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

|Service|URL POST|Identifiant d’accès|
|-|-|-|
|OmniaKey|`https://api.omniakey.com/v1/alpha/search`|Clé OmniaKey autorisée à appeler `jev-latest`|
|TypeSafe en direct|`https://api.typesafe.ai/v1/systemone`|Clé TypeSafe|

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](https://omniakey.com/fr/jev-latest) 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)](https://docs.omniakey.com/en/quick-start) 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.

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

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

|Type|Définition de la question|Champs renvoyés|Lecture|
|-|-|-|-|
|`choice`|Options et descriptions, jusqu’à 255 options|`choice`, `probabilities`, `confidence`|Étiquette choisie et distribution entre les options|
|`score`|Barème ordonné de 2–10 niveaux|`score`, `legend`, `probabilities`, `confidence`|Niveau pondéré par les probabilités, éventuellement décimal|
|`noul`|Question oui/non, critères `true` / `false` facultatifs|`noul`|Probabilité de oui entre 0 et 1, pas un booléen|

La réponse contient aussi `model` et `usage.input_tokens` / `usage.output_tokens`. À la date de vérification, `jev-latest` pointe vers `jev-1.14.0`. Un alias peut évoluer : enregistrez la version réellement utilisée, et écrivez `jev-1.14.0` si elle doit rester fixe.

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.

```json
{
  "model": "jev-1.14.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 du guide API Jev 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.

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

```javascript
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](https://docs.typesafe.ai/api).

## 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](https://omniakey.com/fr/blog/jev-model-explained) 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

|Statut TypeSafe direct|Premier contrôle|Action|
|-|-|-|
|`401`|Service auquel appartient la clé et en-tête Bearer|Corriger l’identifiant, sans réessayer la même clé invalide|
|`422`|Champs obligatoires, type et structure de `criteria`|Corriger le champ indiqué|
|`429`|Quota de requêtes ou de tokens|Respecter `Retry-After` si présent ; attente exponentielle plafonnée avec variation aléatoire|
|`529`|Surcharge temporaire|Réessayer avec un nombre d’essais et une durée totale limités|

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 API Jev dédié à l’intégration OmniaKey. La [référence TypeSafe](https://docs.typesafe.ai/api) définit le contrat direct et la [page des modèles](https://docs.typesafe.ai/models) 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.14 accepte du texte par défaut et renvoie les décisions typées décrites ici. Convertissez les contenus non textuels en texte ou en champs structurés ; l’entrée d’images de la 1.14 reste derrière un réglage expérimental. 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](https://docs.typesafe.ai/api)
- [Modèles, prix, alias et quotas](https://docs.typesafe.ai/models)
- [Interpréter la confiance](https://docs.typesafe.ai/confidence)
- [Limites de Jev 1.13](https://docs.typesafe.ai/model-jaggedness/jev-1.13)