Documentation
Groupes de clés
Donnez à chacun de vos clients ses propres clés API, regroupez-les dans un groupe, consultez ce que chaque client et chaque clé a dépensé sur n’importe quelle période, et plafonnez ce que chaque client peut dépenser en un mois. Un compte, un solde.
Un groupe est un dossier de clés API dans votre compte, par exemple un par client : CID000001, CID000002. Une clé d’un groupe appelle l’API comme n’importe quelle autre clé, et un groupe n’a ni solde, ni rechargements, ni connexion qui lui soient propres ; il peut avoir une limite de dépenses mensuelle sur l’ensemble de ses clés. Une clé appartient à un groupe ou à aucun.
Configurer des groupes en trois étapes
- Créez un groupe. Sur la page Clés API, choisissez « Nouveau groupe » et donnez-lui le nom du client.
- Ajoutez-y des clés. Choisissez « Nouvelle clé » dans l’en-tête du groupe pour y créer une clé. Pour classer une clé existante, ouvrez son menu et choisissez « Déplacer vers un groupe ».
- Lire les chiffres. La page Clés API affiche ce que chaque clé a dépensé pendant ce mois civil et le total de chaque groupe. La page Utilisation affiche les mêmes clés sous leurs groupes pour aujourd’hui, les 7 ou 30 derniers jours, ce mois-ci, le mois dernier, ou des jours que vous choisissez, jusqu’à 90.
Consulter un mois et l’exporter
Sur la page Utilisation, choisissez « Le mois dernier » (ou « Ce mois-ci », ou « Personnalisé » pour des jours de votre choix) en haut. Sous « Par clé API », l’en-tête de chaque groupe indique son coût et ses appels. Le menu des groupes en haut restreint toute la page à un groupe : ses chiffres, son graphique, ses modèles et ses appels. « Exporter en CSV » télécharge ce que la page affiche, avec la même période et le même groupe, par clé ou par jour.
Par clé, le fichier compte une ligne par clé et par groupe, et s’appelle par exemple kunavo-cost-by-key_2026-10-01_2026-10-31.csv. Il liste chaque clé ayant passé des appels pendant la période, y compris les clés révoquées, sous le groupe où chaque appel a eu lieu, ainsi que chaque clé active sans appel dans son groupe actuel, à 0, pour que la liste des clés de chaque client soit complète. Les groupes suivent l’ordre du tableau de bord, les clés de chaque groupe de la plus chère à la moins chère, et les clés sans groupe en dernier. Par jour, le fichier commence par une colonne date et compte une ligne pour chaque jour où une clé a passé des appels dans un groupe.
| Colonne | Contenu |
|---|---|
group | Le groupe où les appels ont eu lieu ; vide pour les appels passés hors de tout groupe. Un groupe supprimé depuis porte (deleted) après son nom. |
key_name | Le nom de la clé. |
key_prefix | Le début de la clé, tel que l’affiche le tableau de bord. Jamais la clé entière. |
key_status | active ou revoked. |
calls | Appels effectués avec la clé sur la période. |
errors | Parmi ces appels, ceux qui ont échoué. Un appel échoué ne coûte rien. |
input_tokens | Tokens d’entrée, lectures et écritures de cache comprises. |
output_ | Tokens de sortie. |
cached_ | Parmi les tokens d’entrée, ceux lus depuis le cache de prompt. |
cache_ | Parmi les tokens d’entrée, ceux écrits dans le cache de prompt. |
cost_usd | Ce qui a été facturé pour les appels, en dollars américains, à huit décimales. |
=, +, - ou @ est écrit précédé d’une apostrophe, pour qu’un tableur l’affiche comme du texte au lieu de l’exécuter comme une formule.Plafonner ce que chaque groupe dépense en un mois
Ouvrez le menu d’un groupe sur la page Clés API et choisissez « Définir la limite mensuelle ». La limite compte ce que toutes les clés du groupe dépensent ensemble pendant un mois civil (UTC) : les appels passés par chaque clé pendant qu’elle était dans le groupe. Une requête qui ferait dépasser la limite au groupe est refusée avec un code 402 et n’est pas facturée. Laissez le champ vide pour ne fixer aucune limite, ou indiquez 0 pour suspendre toutes les clés du groupe sans en révoquer aucune.
La limite mensuelle propre d’une clé s’applique toujours, et la première limite atteinte refuse la requête. L’en-tête du groupe affiche son mois par rapport à la limite, avec « Limite atteinte » dès que des requêtes sont refusées, et « Suspendu » quand la limite est de 0.
Kunavo écrit à l’adresse de votre compte quand un groupe, ou une clé dotée de sa propre limite, a utilisé 80 % de sa limite mensuelle, puis à nouveau quand des requêtes commencent à être refusées à cause d’elle : au plus un e-mail de chaque sorte par mois et par limite.
Comment les montants sont comptés
- Le coût est le montant facturé. Le coût de chaque appel est le montant prélevé sur votre solde à la fin de l’appel. Un appel échoué ne coûte rien.
- Les mois et les jours sont en UTC. Ce mois-ci commence le 1er à 00:00 UTC. À Yangon (UTC+6:30), par exemple, octobre se termine le 1er novembre à 06:30, heure locale. La page Utilisation indique les dates de la période affichée.
- Un appel compte dans le groupe où se trouvait sa clé au moment de l’appel. Déplacez une clé vers un autre groupe et seuls ses appels suivants y comptent ; ses appels antérieurs restent où ils étaient. Le total du mois d’un groupe sur la page Clés API peut donc différer de la somme des clés listées dessous à présent.
- Une clé révoquée reste dans son groupe. Ce qu’elle a dépensé avant sa révocation compte toujours dans les totaux de ce groupe et figure dans l’export.
- Un groupe supprimé garde ses appels. Ils restent sous son nom, signalé comme supprimé, sur la page Utilisation et dans l’export, et le nom peut resservir pour un nouveau groupe.
- Trois endroits, un seul montant. Pour un mois civil donné, le total d’un groupe sur la page Clés API, son total sous « Ce mois-ci » sur la page Utilisation et la somme de ses lignes dans le CSV sont identiques, au centime près.
Questions
- Chaque groupe a-t-il son propre solde ? Non. Tous les groupes puisent dans le solde unique de votre compte. Pour plafonner ce qu’un client peut dépenser, définissez une limite mensuelle sur son groupe, ou sur chacune de ses clés.
- Mes clients peuvent-ils se connecter pour voir leur utilisation ? Non. Les groupes ne sont visibles que par vous. Une clé peut consulter sa propre utilisation avec GET /v1/usage, qui n’indique pas son groupe. Quand son groupe a une limite mensuelle,
GET /v1/balanceindique à la clé cette limite et ce que tout le groupe a dépensé ce mois-ci, mais pas le nom du groupe. - Que se passe-t-il si je supprime un groupe ? Vous choisissez : ses clés continuent de fonctionner, désormais sans groupe, ou elles sont révoquées avec le groupe. Dans les deux cas, les appels qu’elles ont passés restent sous le nom du groupe.
- Et si une clé passe d’un client à un autre ? Déplacez-la dans le groupe de l’autre client : ses appels y comptent à partir de là, et ses appels antérieurs restent chez le premier client.
- Puis-je consulter d’autres périodes ? Oui : choisissez « Personnalisé » sur la page Utilisation et jusqu’à 90 jours. Pour un programme, GET /v1/usage renvoie le coût d’une clé par jour sur la même période.
Pour créer, grouper, plafonner et révoquer les clés d’un client depuis vos propres outils plutôt qu’à la main, utilisez l’API de gestion. Ses clés sont un identifiant distinct, et elles ne fonctionnent que sur cette API.