Comment obtenir une clé API Jev (TypeSafe AI) ?

Jev est le modèle de décision de TypeSafe AI. Vous lui envoyez une partie de l'état et un ensemble de questions typées, et il répond avec des probabilités au lieu de prose. Ce guide couvre la clé API Jev et votre première requête ; pour comprendre ce qu'est Jev et pourquoi il renvoie des nombres plutôt que du texte, lisez d'abord ce qu'est Jev. Pour être clair, étant donné que les résultats de recherche sont confus : il s'agit de Jev, le modèle TypeSafe AI, et non de FaZe Jev le YouTuber ni du vaccin JEV.

Une clé API Jev fonctionne comme n'importe quel autre jeton d'authentification (bearer token), donc si vous êtes nouveau dans ce concept, qu'est-ce qu'une clé API couvre les bases. L'accès direct à l'API est en accès anticipé, donc la première étape est de sortir de la liste d'attente. Ensuite, vous créerez la clé, apprendrez la forme de la requête, appellerez le point de terminaison avec curl et le SDK Python, lirez les champs de probabilité, et intégrerez la requête dans Apidog avec des assertions sur ces probabilités. Si vous ne pouvez pas attendre, le même modèle est disponible sur Vercel AI Gateway sans liste d'attente ; la FAQ couvre cette voie.

Étape 1 : obtenir un accès anticipé, puis créer la clé

Jev est en accès anticipé au moment où nous écrivons ces lignes. Le communiqué de lancement de TypeSafe indique qu'il "fait sortir les développeurs de la liste d'attente aussi vite que possible", alors rejoignez la liste d'attente sur typesafe.ai et attendez l'invitation à la console ; il n'y a pas encore d'inscription en libre-service. Une fois votre compte console actif, allez sur console.typesafe.ai/settings/keys et créez une clé. Copiez-la une seule fois et traitez-la comme un mot de passe.

Exportez-la comme variable d'environnement au lieu de la coller dans le code :

export TYPESAFE_API_KEY="ts_..."

Les exemples curl officiels et le SDK Python lisent tous deux `TYPESAFE_API_KEY` depuis l'environnement, donc une seule variable couvre tous les exemples ci-dessous. Si une clé se retrouve un jour dans un commit, faites-la pivoter dans la console et exécutez un contrôle de fuite de clé API sur l'ensemble du dépôt.

Étape 2 : comprendre la forme de la requête

Chaque appel Jev est un simple `POST https://api.typesafe.ai/v1/systemone` avec trois champs dans le corps, documentés dans la référence de l'API TypeSafe :

Chaque question est l'une des trois primitives :

La réponse contient également model et usage.input_tokens / usage.output_tokens. Les questions de différents types peuvent partager un même état et être renvoyées en un seul aller-retour.

Étape 3 : effectuer la première requête avec curl

Cette requête exécute les trois primitives sur un seul ticket de support :

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "Ma carte a été débitée deux fois pour une seule commande et personne n'a répondu en trois jours.",
    "questions": {
      "needs_review": {
        "type": "noul",
        "instructions": "Ce ticket nécessite-t-il un agent humain ?",
        "criteria": {
          "true": "argent, légal, ou une plainte sans réponse",
          "false": "une question de routine qu'un bot peut clore"
        }
      },
      "route": {
        "type": "choice",
        "instructions": "Acheminez ce ticket à une équipe.",
        "criteria": {
          "billing": "problèmes de paiement ou de facturation",
          "shipping": "problèmes de livraison",
          "technical": "bugs d'application"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "Quelle est l'urgence de ce ticket ?",
        "criteria": ["faible", "moyenne", "élevée"]
      }
    }
  }'

Une réponse ressemble à ceci (les valeurs sont illustratives) :

{
  "model": "jev-1.13.0",
  "answers": {
    "needs_review": { "type": "noul", "noul": 0.97 },
    "route": {
      "type": "choice",
      "choice": "billing",
      "confidence": 0.98,
      "probabilities": { "billing": 0.98, "shipping": 0.01, "technical": 0.01 }
    },
    "urgency": {
      "type": "score",
      "score": 1.6,
      "confidence": 0.62,
      "legend": { "0": "faible", "1": "moyenne", "2": "élevée" },
      "probabilities": { "0": 0.02, "1": 0.36, "2": 0.62 }
    }
  },
  "usage": { "input_tokens": 190, "output_tokens": 0 }
}

Étape 4 : lire les champs de probabilité

Lisez les chiffres avec précision :

• `noul` est la probabilité de "oui". 0.97 signifie que Jev est sûr à 97 % que ce ticket nécessite un humain.
• `choice` est l'option la plus probable, `probabilities` liste toutes les options, et `confidence` indique à quel point le choix était décisif. Un routage à 0.98 est sûr à automatiser ; un routage à 0.51 avec 0.47 pour la deuxième meilleure option est un coup de dés.
• `score` est la position pondérée par la probabilité sur les niveaux ordonnés, donc 1.6 se situe entre "moyenne" (1) et "élevée" (2). `legend` mappe chaque indice à son étiquette, et `probabilities` montre la répartition complète.

Comme la sortie est une distribution et non une étiquette, c'est vous qui fixez le seuil, pas le modèle. C'est pourquoi les assertions de l'étape 6 testent les nombres.

Étape 5 : le même appel avec le SDK Python

Installez le SDK ; le client récupère `TYPESAFE_API_KEY` depuis l'environnement :

pip install typesafe-sdk

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="Ma carte a été débitée deux fois pour une seule commande et personne n'a répondu en trois jours.",
        questions={
            "needs_review": Noul(
                instructions="Ce ticket nécessite-t-il un agent humain ?",
                criteria={"true": "argent, légal, ou une plainte sans réponse",
                          "false": "une question de routine qu'un bot peut clore"},
            ),
            "route": Choice(
                instructions="Acheminez ce ticket à une équipe.",
                criteria={"billing": "problèmes de paiement ou de facturation",
                          "shipping": "problèmes de livraison",
                          "technical": "bugs d'application"},
            ),
            "urgency": Score(
                instructions="Quelle est l'urgence de ce ticket ?",
                criteria=["faible", "moyenne", "élevée"],
            ),
        },
    )

print(response.nouls["needs_review"].noul)
print(response.choices["route"].choice, response.choices["route"].probabilities)
print(response.scores["urgency"].score)

Les réponses sont regroupées par type sur l'objet réponse (`nouls`, `choices`, `scores`). Il existe un SDK JavaScript de forme similaire, et si vous utilisez déjà Vercel AI Gateway, `experimental_evaluate` du SDK AI 7 appelle le modèle sous le nom `typesafe-ai/jev`, avec une différence : le type de question booléenne renvoie un champ `probability` au lieu de `noul`.

Étape 6 : stocker et tester la clé API Jev dans Apidog

Curl prouve que la clé fonctionne une fois. Apidog rend la requête réexécutable, assertable et mockable pour toute l'équipe.

Stockez la clé comme variable secrète. Créez un environnement appelé `TypeSafe` et ajoutez `TYPESAFE_API_KEY` comme secret pour que sa valeur reste masquée dans l'interface utilisateur et hors des exportations ; les environnements et variables secrètes d'Apidog expliquent la configuration. Définissez l'authentification sur la requête comme Bearer Token avec `{{TYPESAFE_API_KEY}}` comme valeur.

Construisez la requête POST. Ajoutez un POST à `https://api.typesafe.ai/v1/systemone`, collez le corps JSON de l'Étape 3, et envoyez-le. Le panneau de réponse affiche l'arbre des réponses, vous permettant de vérifier les probabilités avant d'écrire une assertion.

Assert sur les probabilités, pas sur la prose. Dans le constructeur d'assertion visuel, pointez les expressions JSONPath vers les champs qui vous intéressent :

• `$.answers.needs_review.noul` est supérieur à `0.9`
• `$.answers.route.choice` est égal à `billing`
• `$.answers.route.probabilities.billing` est supérieur à `0.8`
• `$.answers.urgency.score` est supérieur ou égal à `1`
• `$.usage.input_tokens` est inférieur à `1000`

Si vous préférez les scripts, le post-processeur accepte l'API familière `pm` :

const body = pm.response.json();
pm.test("ticket signalé pour un humain", () => {
  pm.expect(body.answers.needs_review.noul).to.be.above(0.9);
});
pm.test("acheminé vers la facturation", () => {
  pm.expect(body.answers.route.choice).to.eql("billing");
});

Enregistrez-le comme scénario de test. Déposez la requête dans un scénario de test avec un petit fichier CSV de tickets et de routages attendus, et exécutez-le à chaque modification de vos instructions ou critères. Les modifications de prompt sont des changements de code ; un scénario de dix lignes détecte la modification qui déplace discrètement un 0.95 à 0.6. Le même scénario s'exécute en CI via l'Apidog CLI, de sorte qu'une régression bloque la fusion.

Mockez la forme de réponse déclarée. Définissez le schéma de réponse sur le point de terminaison (les trois objets de réponse plus `usage`), et le mock intelligent d'Apidog servira immédiatement des probabilités fictives réalistes. Le frontend peut construire le badge "nécessite examen" et l'interface utilisateur de routage contre le mock avant que le backend ne soit livré, puis échanger l'URL du mock contre le point de terminaison réel avec un seul changement d'environnement.

Pour les places de planification : le plan gratuit d'Apidog inclut 4 utilisateurs, et les niveaux payants sont par place.

Seuils dans le code

Une fois les assertions passées, les mêmes chiffres pilotent la logique de production. Gardez les seuils en un seul endroit et nommez-les :

REVIEW_THRESHOLD = 0.9
AUTO_ROUTE_CONFIDENCE = 0.85

needs_review = response.nouls["needs_review"].noul >= REVIEW_THRESHOLD
route = response.choices["route"]

if route.confidence >= AUTO_ROUTE_CONFIDENCE and not needs_review:
    assign(ticket, team=route.choice)
else:
    queue_for_human(ticket, suggested=route.choice)

Enregistrez la carte complète des `probabilities` avec chaque décision afin de pouvoir ajuster les seuils à partir de données réelles ultérieurement, et faites de la révision humaine la valeur par défaut lorsque la confiance est faible ; le modèle vous dit qu'il n'est pas sûr.

Limites, tarifs et modèles

Directement depuis la page des modèles TypeSafe :

À ce prix, un million de tickets courts coûtent moins de 10 $. TypeSafe déclare également que Jev n'est pas entraîné sur les requêtes ou réponses des clients.

Erreurs courantes et comment les corriger

Un 422 est celui que vous rencontrerez le plus souvent en itérant ; le schéma de point de terminaison de l'Étape 6 en détecte la plupart avant que la requête ne quitte votre machine.

FAQ

Y a-t-il un niveau gratuit pour l'API Jev ? La documentation publique liste les prix par jeton et ne décrit pas de niveau gratuit ou de crédits de démarrage, et l'accès lui-même est actuellement sur liste d'attente. Vérifiez la console une fois que votre invitation arrive pour l'offre actuelle, et considérez tout chiffre que vous voyez ailleurs comme non officiel.

Puis-je obtenir plusieurs réponses à partir d'une seule requête ? Oui. `questions` est un mappage, donc un `noul`, un `choice` et un `score` peuvent tous s'exécuter sur un seul état en un seul appel. C'est moins cher que trois requêtes et cela maintient la cohérence des réponses car elles partagent une seule entrée.

En quoi cela diffère-t-il des sorties structurées d'un modèle de chat ? Les sorties structurées forcent un modèle linguistique à émettre un JSON valide, mais les valeurs à l'intérieur sont toujours des jetons générés, et un champ "confiance" est un texte que le modèle a écrit sur lui-même. Jev renvoie des probabilités mesurées comme sortie native, c'est pourquoi vous pouvez affirmer que `noul > 0.9` et faire confiance à la comparaison.

Ai-je besoin du SDK de TypeSafe si j'utilise Vercel ? Non. Le SDK Vercel AI expose Jev via `experimental_evaluate` avec `typesafe-ai/jev` comme identifiant de modèle. Vous vous authentifierez avec votre clé AI Gateway au lieu d'une clé TypeSafe, et la réponse booléenne sera renvoyée sous la forme `probability`.

Prochaines étapes

Vous avez maintenant une clé API Jev, une requête fonctionnelle en curl et Python, et une compréhension claire de `noul`, `choice` et `score`. Placez la requête dans Apidog, ajoutez les assertions de probabilité, et enregistrez le scénario de test afin que les modifications de prompt soient testées comme du code. Téléchargez Apidog pour suivre le guide.