TokenLab

Guides essentiels

Construire une intégration TokenLab fiable

Gardez le contrôle sur les coûts, les tentatives de nouvelle tentative (retries), les clés API et les enregistrements de requêtes

Une bonne intégration rend les choix de prix et de modèles visibles, survit aux pannes réseau courantes et n'expose jamais une clé API dans le navigateur. Les pratiques ci-dessous s'appliquent aux API de chat, d'image, de vidéo, d'audio et aux autres API TokenLab.

Choisir des modèles avec des données à jour

Les noms, les capacités et les prix des modèles changent. Consultez l'API Models API ou les pages des modèles au lieu de conserver une liste permanente dans votre code ou votre documentation.

Pour un nouveau cas d'utilisation :

  1. Filtrez les modèles selon la capacité dont votre produit a besoin.
  2. Comparez leurs prix TokenLab actuels.
  3. Testez un petit ensemble avec des requêtes utilisateur représentatives.
  4. Gardez l'ID du modèle explicite dans chaque requête.

Ne changez pas de modèle silencieusement. Un remplacement peut modifier la qualité de sortie, le prix, la longueur du contexte, les outils disponibles ou la prise en charge des médias.

Plafonner les coûts

Pour les modèles de texte, limitez la sortie à la longueur que votre produit peut réellement utiliser. Le nom du paramètre dépend de l'API et du modèle ; vérifiez donc la page du modèle avant d'envoyer max_tokens ou max_output_tokens.

Des instructions plus courtes ne sont pas automatiquement meilleures, mais un contexte dupliqué et du texte standard répété ajoutent toujours des jetons d'entrée (input tokens). Gardez les instructions stables concises et n'envoyez que l'historique nécessaire pour la réponse suivante.

Pour les requêtes d'image, de vidéo, de musique, de 3D et de Worlds, le coût dépend souvent du nombre de sorties, de la durée, de la résolution ou d'une autre option média. Affichez l'estimation actuelle avant qu'un utilisateur ne confirme une génération coûteuse, chaque fois que l'API peut en fournir une.

Diffuser les réponses textuelles longues (Streaming)

Le streaming affiche la réponse au fur et à mesure qu'elle arrive et évite à l'utilisateur d'attendre la réponse complète. Cela ne réduit pas le coût en jetons.

Pour un exemple complet avec configuration client et vérifications de complétion, voir Streaming.

Gérez une déconnexion comme une réponse incomplète. Ne présentez pas une sortie partielle comme terminée avec succès, et ne répétez pas une requête automatiquement si cela peut créer un second effet secondaire ou une facturation supplémentaire.

Ne réessayer que lorsque c'est sûr

Réessayez les réponses 429 après Retry-After ou retry_after. Un court délai exponentiel (exponential backoff) est approprié pour les réponses 5xx transitoires. Les erreurs d'authentification, de validation, de solde et de longueur de contexte nécessitent une modification de la part de l'application ou de l'utilisateur ; renvoyer la même requête ne les corrigera pas.

Voir Limites de débit pour un exemple de nouvelle tentative bornée qui respecte Retry-After et désactive les nouvelles tentatives du SDK en double.

Définissez une limite de tentatives et une limite de temps totale. Pour la création de médias, enregistrez l'ID de tâche renvoyé. Pour les requêtes listées dans Retry safely with an idempotency key, envoyez une Idempotency-Key, afin qu'une nouvelle tentative après un délai d'attente ne puisse pas exécuter ou facturer la même requête deux fois.

Garder les clés API sur le serveur

N'intégrez jamais une clé API TokenLab dans le JavaScript d'un navigateur, un bundle d'application mobile, un dépôt public ou un journal visible par le client.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

Utilisez des clés API distinctes pour le développement, la production et les applications indépendantes. Donnez à chaque clé uniquement les modèles et la limite de dépenses dont elle a besoin. Révoquez immédiatement une clé si elle a pu être exposée.

Conserver des enregistrements de requêtes utiles

Stockez les identifiants qui vous permettent de relier une action utilisateur aux enregistrements d'utilisation et de support :

  • request_id pour la requête API
  • task_id pour la génération asynchrone
  • billing_transaction_id lorsqu'il est renvoyé
  • ID du modèle et point de terminaison (endpoint)
  • Votre propre ID utilisateur, projet ou travail

Ne journalisez pas les clés API, les jetons de gestion, les prompts privés complets, les médias privés ou les URLs signées. Les enregistrements d'utilisation dans la Console et l'API de gestion sont la source des montants facturés ; le nombre de jetons de réponse du modèle seul peut ne pas décrire la charge finale.

Concevoir pour le travail asynchrone

Les API d'image, de vidéo, de musique, de 3D et de Worlds peuvent renvoyer une réponse avant que le résultat ne soit prêt. Enregistrez l'ID de tâche, interrogez GET /v1/tasks/{id}, et arrêtez-vous uniquement à completed ou failed. Une recherche de statut failed ne signifie pas que la génération elle-même a échoué.

Voir Tâches asynchrones et polling pour la gestion de l'annulation, du délai d'attente et des requêtes en double.

Avant le lancement

  • Exécutez des requêtes représentatives avec le modèle exact et le format d'API que vous allez déployer.
  • Vérifiez à la fois les réponses de succès et les erreurs courantes.
  • Confirmez que le prix affiché dans votre produit correspond au prix TokenLab actuel.
  • Rendez les rafraîchissements, les délais d'attente réseau et les clics répétés sûrs.
  • Permettez de retracer un résultat visible par l'utilisateur jusqu'à son Request ID.

Sur cette page