Tovanix
Tovanix

Utiliser la passerelle API IA

Une seule clé API pour appeler les modèles de plusieurs fournisseurs, facturés à l’usage réel sur le solde du compte :

  • Créez la clé dans « Services IA → Passerelle API → Clés API », choisissez un groupe tarifaire par fournisseur et, si besoin, un plafond de dépenses mensuel, modifiable ensuite dans la liste des clés
  • Trois formats de requête sont pris en charge, OpenAI, Anthropic et Gemini ; l’intégration demande généralement de ne changer que l’adresse de la passerelle et la clé
  • Prix = prix officiel × coefficient du groupe tarifaire ; certains groupes ont un tarif d’heures creuses
  • Un montant est réservé avant l’appel puis réglé sur l’usage réel, et le solde est débité en une seule fois chaque minute
  • « Utilisation et journaux » présente les statistiques et le détail de chaque appel

À quoi sert la passerelle

La passerelle API des Services IA est un point d’accès unique aux grands modèles : une seule clé API permet d’appeler les modèles de plusieurs fournisseurs, facturés à l’usage réel sur le solde du compte, sans ouvrir de compte ni recharger chez chaque fournisseur.

  • Les SDK officiels fonctionnent tels quels : l’intégration consiste généralement à changer base_url et api_key, sans modifier les structures des requêtes et réponses.
  • Trois formats de requête sont pris en charge, OpenAI, Anthropic et Gemini, avec des appels croisés entre formats : par exemple, le SDK OpenAI peut appeler un modèle Claude, la passerelle se chargeant de la conversion.
  • La tarification se fait par groupe tarifaire : dans un groupe, un modèle n’a qu’un seul prix. Si un groupe contient plusieurs routes, une route en erreur est automatiquement remplacée par la suivante du même groupe, au même prix.

Créer une clé API

  • Ouvrir la page Clés API: Dans la console, ouvrez « Services IA → Passerelle API → Clés API », puis cliquez sur « Créer une clé » en haut à droite.
  • Saisir le nom, les groupes tarifaires et le plafond mensuel: Nommez la clé d’après son usage, par exemple production, test ou cursor. Pour chaque fournisseur qui propose plusieurs groupes, choisissez un « Groupe tarifaire » ; sans choix, le groupe par défaut de ce fournisseur s’applique. Un plafond de dépenses mensuel vide signifie illimité, et 0 bloque toute dépense ce mois-ci ; vous pourrez ensuite le modifier depuis la liste des clés avec « Modifier le plafond », après vérification de votre identité.
  • Vérifier votre identité: Après avoir cliqué sur « Créer », vous devez vérifier votre identité : si l’authentification à deux facteurs (2FA) est activée, saisissez le code à 6 chiffres de votre application d’authentification ; sinon, saisissez le code reçu par e-mail. Une fois la vérification réussie, vous pouvez créer d’autres clés ou modifier des plafonds pendant 10 minutes dans la même session sans nouvelle vérification.
  • Enregistrer immédiatement la clé en clair: La clé commence par sk-nc- suivi d’une chaîne et n’est affichée qu’une fois, car le serveur ne stocke que son empreinte. Copiez-la dans votre gestionnaire de mots de passe avant de fermer la fenêtre.

Après fermeture, la clé en clair disparaît définitivement : la plateforme n’a qu’une empreinte. Sans sauvegarde, il faut supprimer la clé et en créer une autre. La suppression est immédiate et déconnecte tout ce qui l’utilise encore.

Groupes tarifaires

Le groupe tarifaire détermine le prix appliqué quand cette clé appelle les modèles d’un fournisseur : prix = prix officiel × coefficient du groupe. Les groupes sont définis par fournisseur : chacun a ses propres groupes et un groupe par défaut.

  • À la création d’une clé, un choix n’est demandé que pour les fournisseurs qui ont au moins deux groupes ; ceux qui n’en ont qu’un ne demandent rien. Un fournisseur pour lequel vous n’avez rien choisi utilise son groupe par défaut.
  • La colonne « Groupe » de la liste des clés indique, pour chaque fournisseur, le groupe choisi et son coefficient ; cliquez sur « Changer » pour le modifier : le nouveau groupe s’applique dès l’appel suivant.
  • Les appels n’empruntent que les routes du groupe choisi et ne basculent jamais vers un autre groupe : le prix d’un même modèle ne change donc pas selon la route utilisée.

Si le groupe choisi pour un fournisseur est désactivé, la liste affiche « Groupe désactivé » et les appels de cette clé aux modèles de ce fournisseur sont refusés (HTTP 403). Cliquez sur « Changer » pour choisir un autre groupe.

Effectuer votre premier appel

L’adresse de la passerelle est le domaine de la console. La page « Tableau de bord » propose des exemples curl aux trois formats OpenAI, Anthropic et Gemini, et la fenêtre affichée après la création d’une clé en contient un aussi, avec l’adresse de la passerelle déjà renseignée.

  • OpenAI — /v1/chat/completions — En-tête Authorization, avec pour valeur Bearer suivi de votre clé
  • Anthropic — /v1/messages — En-tête x-api-key
  • Gemini — /v1beta/models/nom_du_modèle:generateContent ; en diffusion continue, :streamGenerateContent — En-tête x-goog-api-key, ou paramètre d’URL ?key=
  • Avec un SDK officiel, dirigez base_url vers la passerelle et définissez api_key sur cette clé ; le reste du code reste inchangé.
  • Sont aussi disponibles /v1/models (liste des modèles disponibles), /v1/embeddings (vecteurs de texte) et /v1/images/generations (génération d’images, facturée à l’image), tous appelés au format OpenAI.
  • Le champ model de la requête prend l’identifiant de modèle affiché sur la carte du « Catalogue des modèles ». Un identifiant erroné ou un modèle non publié renvoie 404.

Catalogue des modèles et affichage des prix

Le catalogue liste tous les modèles disponibles par fournisseur et permet une recherche par nom, slug, description ou capacité, avec des paramètres comme le contexte et la sortie maximale.

  • Prix = prix officiel × coefficient du groupe tarifaire. L’onglet « Tous » affiche les prix du groupe par défaut de chaque fournisseur ; en ouvrant un fournisseur, vous pouvez passer d’un de ses groupes à l’autre. Le multiplicateur affiché en haut à droite de la carte est le coefficient du groupe actuel.
  • Les modèles facturés au jeton ont deux prix, entrée et sortie, exprimés par million de jetons ; s’il existe un prix de lecture du cache, il figure sur une ligne à part. Les modèles d’image, d’audio ou de vidéo facturés à l’image, à la seconde, à la minute ou à l’appel affichent directement leur prix unitaire sur la carte.
  • Certaines cartes portent une ligne « Prompts de plus de » une certaine longueur, avec son prix : si le prompt d’une requête dépasse cette longueur, toute la requête est facturée au prix de cette ligne.
  • Pour les modèles dont la carte comporte une ligne « Recherche web », l’utilisation de la recherche web intégrée au modèle est facturée en plus, au nombre de recherches.

Si un groupe a un tarif d’heures creuses, la carte affiche « Heures creuses » et le coefficient ; au survol, les heures pleines apparaissent. En dehors des heures pleines, le prix du groupe est encore multiplié par ce coefficient, selon l’heure d’envoi de la requête. Une carte marquée « Pas encore de route dans ce groupe » liste les groupes dans lesquels ce modèle est disponible ; « Indisponible » signifie qu’aucun groupe ne peut l’appeler pour le moment.

Utilisation et journaux

Dans « Services IA → Passerelle API → Utilisation et journaux », la partie supérieure présente les statistiques, sur 24 heures, 7 jours, 30 jours ou 90 jours (7 jours par défaut) ; la partie inférieure détaille les appels.

  • Statistiques : nombre de requêtes, montant facturé, total des jetons (cache compris), taux de réussite et latence moyenne, ainsi que l’évolution quotidienne et les classements par modèle et par clé.
  • Détail : pour chaque appel, l’heure, le modèle, la diffusion en continu ou non, les jetons d’entrée / de sortie / de cache, le montant facturé, le coefficient, la latence et le statut, avec un filtre par slug de modèle.
  • Le détail n’enregistre que les appels réellement transmis à un modèle ; leur statut est « Réussite » ou « Erreur », et les entrées « Erreur » ne sont pas facturées. Les requêtes refusées avant d’atteindre un modèle (par exemple clé invalide, plafond mensuel atteint, solde insuffisant ou groupe désactivé) n’apparaissent pas dans le détail : leur cause figure dans le message d’erreur renvoyé par l’API.
  • La colonne « Coefficient » indique le coefficient du groupe, sans la réduction des heures creuses ; le montant réellement débité pour chaque appel est celui de la colonne « Facturé en USD ».

Comment vous êtes facturé

Les frais sont débités du solde du compte selon l’usage réel, sans rechargement séparé pour ce service. Coût de chaque appel = prix officiel × coefficient du groupe ; si le groupe a des heures creuses, ce coût est en plus multiplié pendant ces heures par le coefficient d’heures creuses, selon l’heure d’envoi de la requête.

  • Avant l’appel, un montant est réservé d’après la longueur de l’entrée et la sortie maximale du modèle ; à la fin, l’appel est réglé sur l’usage réel et l’excédent est libéré. Si le solde disponible ne couvre pas cette réserve, la passerelle renvoie solde insuffisant (HTTP 402), avec dans le message d’erreur le montant à réserver et le montant actuellement disponible.
  • Les frais s’accumulent appel par appel et sont débités du solde en une seule fois chaque minute ; les factures de « Finances » contiennent une ligne « Utilisation des services IA (récapitulatif sur 1 heure) » par heure.
  • Quand le solde disponible descend à $5 ou moins, la plateforme vous prévient une fois, par les messages sur le site et vos autres canaux de notification ; s’il remonte au-dessus de $5 puis redescend, vous êtes de nouveau prévenu. Pendant cette période, les réponses de l’API portent les en-têtes X-Tovanix-Balance-Low: 1 et X-Tovanix-Balance-Available (montant actuellement disponible), qui permettent à vos programmes de signaler la recharge à l’avance.
  • Chaque clé peut avoir son propre plafond de dépenses mensuel, calculé par mois civil et rétabli automatiquement le mois suivant. Avant chaque appel, la passerelle vérifie les dépenses du mois augmentées des appels en cours : si le plafond est atteint, l’appel est refusé. Le dernier appel est réglé sur l’usage réel : les dépenses du mois peuvent donc dépasser légèrement le plafond.

Précautions

  • La clé en clair n’apparaît qu’à la création ; enregistrez-la immédiatement.
  • La suppression d’une clé est immédiate et définitive. Pour simplement la suspendre, cliquez sur « Désactiver » dans la liste ; vous pourrez ensuite cliquer sur « Activer ».
  • Un plafond mensuel de 0 bloque la clé pour tout le mois ; 0 ne signifie pas illimité.
  • La passerelle traite les requêtes au niveau standard : un niveau de vitesse indiqué dans la requête (par exemple speed: fast pour Claude ou service_tier pour OpenAI) est ignoré, et le coût est calculé au prix standard.
  • Pour un appel au format Anthropic avec l’outil de recherche web, si la requête ne fixe pas de nombre maximal de recherches, chaque requête effectue au plus 10 recherches.

Dépannage

  • Réponse 401 : clé invalide ou désactivée — Clé mal saisie, supprimée ou désactivée — Sur la page « Clés API », vérifiez que la clé est à l’état « Activé » ; si elle est désactivée, cliquez sur « Activer ». Une clé supprimée ne peut pas être restaurée : créez-en une nouvelle.
  • Réponse 402 : plafond de dépenses mensuel atteint — Les dépenses de cette clé ont atteint le plafond du mois (un plafond de 0 bloque toute dépense ce mois-ci) — Le plafond se rétablit automatiquement le mois suivant. Si vous ne pouvez pas attendre, sur la page « Clés API », cliquez sur « Modifier le plafond » pour cette clé et relevez-le, ou laissez le champ vide pour ne plus avoir de plafond (vérification d’identité requise) ; le nouveau plafond s’applique dès l’appel suivant.
  • Réponse 402 : solde insuffisant — Le solde disponible ne couvre pas la réserve de cette requête — Le message d’erreur indique le montant à réserver et le montant actuellement disponible : rechargez, puis réessayez.
  • Réponse 403 ou 503 : groupe désactivé ou aucune route disponible — Le groupe choisi par la clé pour ce fournisseur est désactivé, ou ce modèle n’a temporairement aucune route disponible dans le groupe — Sur la page « Clés API », cliquez sur « Changer » pour choisir un autre groupe ; la carte du « Catalogue des modèles » indique les groupes dans lesquels ce modèle est disponible. Vous pouvez aussi réessayer plus tard.
  • La facture dépasse le prix de la place de marché — L’onglet « Tous » affiche les prix du groupe par défaut alors que la clé utilise un autre groupe ; ou bien la requête tombait en heures creuses, son prompt dépassait le seuil de contexte long ou elle a utilisé la recherche web — Le montant facturé de chaque entrée dans « Utilisation et journaux » fait foi.
  • Une application en production se déconnecte soudainement — La clé a été supprimée ou désactivée — Une clé désactivée se rétablit avec « Activer » dans la liste ; pour une clé supprimée, créez-en une nouvelle et remplacez l’ancienne dans l’application.

Questions fréquentes

Combien de code faut-il modifier pour l’intégration ?

Généralement deux éléments : diriger base_url vers la passerelle et remplacer api_key par la clé de la plateforme. La passerelle est compatible avec les SDK et protocoles officiels : corps des requêtes, structure des réponses et format de diffusion en continu restent identiques.

Pourquoi ma facture diffère-t-elle du prix du catalogue des modèles ?

L’onglet « Tous » affiche les prix du groupe par défaut de chaque fournisseur ; si votre clé utilise un autre groupe, c’est le prix de ce groupe qui s’applique. Par ailleurs, la réduction des heures creuses, le changement de prix de toute la requête quand le prompt dépasse le seuil de contexte long et la facturation de la recherche web au nombre de recherches peuvent tous faire différer le coût d’un appel du prix affiché. Le montant facturé de chaque entrée dans « Utilisation et journaux » fait foi.

Comment plafonner les dépenses d’un projet ?

Créez une clé dédiée à ce projet et fixez-lui un plafond de dépenses mensuel. Le plafond s’applique par clé, sans effet d’un projet à l’autre ; pour l’ajuster plus tard, cliquez sur « Modifier le plafond » dans la liste des clés (vérification d’identité requise).

Pages connexes: Centre d'aide · Guides et FAQ · Services IA · Documentation API

Chargement…