Appeler l'API TypeSafe depuis un agent : forme de la requête, erreurs, tentatives et épinglage de version

Objectif

Effectuer un premier appel correct, gérer les statuts d'échec documentés, et garder des résultats reproductibles au fil des versions du modèle.

Prérequis

Une clé d'API provenant de la console de l'éditeur (accès anticipé au moment de la rédaction), exportée sous TYPESAFE_API_KEY, que les deux SDK officiels lisent par défaut. Python : pip install typesafe-sdk ou uv add typesafe-sdk. JavaScript (Node.js 20 ou plus récent) : npm install @typesafe-ai/sdk. Le HTTP direct fonctionne sans SDK.

Étapes

1. Construire la requête : POST https://api.typesafe.ai/v1/systemone avec Authorization: Bearer <key> et un corps JSON comportant state (chaîne, objet ou tableau), model (jev-latest ou un identifiant versionné tel que jev-1.13.0) et questions, une carte associant une clé de son choix à une question typée (type valant noul, choice ou score, instructions, et criteria selon ce qu'exige le type).
2. Lire la réponse : model (l'identifiant versionné qui a répondu), answers sous les mêmes clés (une valeur noul ; ou choice, probabilities et confidence ; ou score, legend, probabilities et confidence) et usage avec input_tokens et output_tokens. Dans le SDK Python, les mêmes réponses sont accessibles via response.nouls[...], response.choices[...] et response.scores[...].
3. Gérer les erreurs selon le statut : 401 signale une clé absente ou invalide ; 422 signale que le corps a échoué à la validation, le corps de la réponse nommant le champ en cause ; 429 signale qu'une limite de débit a été dépassée ; 529 signale que le service est surchargé. La référence indique de réessayer les codes 429 et 529 avec un backoff exponentiel, jamais immédiatement.
4. En cas d'utilisation du SDK Python, connaître ses valeurs par défaut : une RetryPolicy avec deux tentatives, un backoff initial de 0.5 s allant jusqu'à 5 s avec gigue (jitter), les statuts réessayables 408, 429 et 5xx, respect_retry_after activé, et un délai d'expiration de 30 s ; la surcharger lorsque l'échéance propre de l'agent est plus courte.
5. Rester dans les budgets documentés : 64k tokens par requête, 32k pour l'état (state) plus la question la plus longue, au maximum 255 options pour Choice et 10 niveaux pour Score. Les dépasser produit un 422, pas une réponse tronquée.
6. Épingler le modèle une fois les seuils calés : les alias évoluent à chaque publication ; GET /v1/models liste les alias que le compte peut envoyer, et les identifiants versionnés sont acceptés qu'ils y figurent ou non.
7. Pour un agent de codage, installer la compétence (skill) de l'éditeur (<coding-agent> plugin marketplace add typesafe-ai/skills et <coding-agent> plugin install typesafe@typesafe-ai pour l'agent de codage, npx skills add typesafe-ai/skills --skill typesafe-ai ailleurs) et la mettre à jour avant utilisation ; l'éditeur attribue les champs de requête ou de réponse inventés à une compétence obsolète.

Résultat attendu

Une requête qui se valide dès le premier essai, un client qui applique un backoff sur les codes 429 et 529 sans marteler le point de terminaison, et des journaux qui nomment le modèle versionné derrière chaque décision.

Limites et base de vérification

Tout ce qui précède correspond à la documentation de l'éditeur telle qu'elle se présentait en septembre 2026 ; les limites de débit sont annoncées comme pouvant changer sans préavis pendant l'accès anticipé, il faut donc considérer le code 429 comme attendu plutôt qu'exceptionnel. Aucune mesure de latence ou de précision n'est avancée.