Jetons et utilisation

Le jeton (token) est l'unité de traitement des modèles et l'unité de facturation de l'API. Cette page explique comment l'estimer avant l'appel et comment lire la consommation réelle après.

Qu'est-ce qu'un jeton#

Un jeton est un fragment de texte : un mot court, une partie de mot long, un chiffre ou un signe de ponctuation. Ordres de grandeur utiles :

Lire la consommation d'une requête#

Chaque réponse non-streamée contient le décompte :

"usage": {
  "prompt_tokens": 1240,      // ce que vous avez envoyé (contexte inclus)
  "completion_tokens": 318,   // ce que le modèle a généré
  "total_tokens": 1558
}

En streaming, ajoutez "stream_options": {"include_usage": true} : un dernier événement, après le texte, portera le champ usage.

Sur la surface Anthropic, le même décompte s'appelle usage.input_tokens / usage.output_tokens.

Ce qui compte dans prompt_tokens#

• Le message system, renvoyé à chaque appel.
• Tout l'historique de conversation que vous retransmettez, l'API est sans état : ce que vous n'envoyez pas n'existe pas pour le modèle.
• Les définitions d'outils (tools) et les résultats d'outils.

C'est le poste de dépense qui grossit le plus vite : dans une conversation de 20 tours, le contexte représente souvent plus de 90 % des jetons facturés.

Réduire sa consommation#

• Tronquer l'historique : ne renvoyez que les N derniers tours, ou un résumé des plus anciens.
• Raccourcir le prompt système : il est facturé à chaque requête.
• Borner la sortie avec max_tokens : le jeton de sortie coûte environ trois fois le jeton d'entrée sur tous les modèles. Le contexte fait le nombre de jetons, la sortie fait leur prix : agissez sur les deux.
• Choisir le bon modèle : l'écart de prix entre mina-flash, mina-low et mina-full est important, comparez-les sur Modèles et prix avant de prendre le plus gros par défaut.
• Ne pas envoyer de documents entiers quand un extrait pertinent suffit.

Estimer avant d'appeler#

Pour un budget prévisionnel, l'approximation « nombre de caractères ÷ 4 » suffit :

def estimer_jetons(texte: str) -> int:
    """Approximation ± 20 % - pour un budget, pas pour une facture."""
    return max(1, len(texte) // 4)

def cout_da(entree: int, sortie: int, prix_in: float, prix_out: float) -> float:
    return (entree * prix_in + sortie * prix_out) / 1_000_000

# tarifs mina-low, à reprendre sur la page Modèles et prix
print(cout_da(8000, 2000, 350, 1000))  # 4.8 DA

const estimerJetons = (texte) => Math.max(1, Math.floor(texte.length / 4));

const coutDa = (entree, sortie, prixIn, prixOut) =>
  (entree * prixIn + sortie * prixOut) / 1_000_000;

// tarifs mina-low, à reprendre sur la page Modèles et prix
console.log(coutDa(8000, 2000, 350, 1000)); // 4.8

Suivre sa consommation#

La page Usage de la plateforme montre, par jour et par modèle : le nombre de requêtes, les jetons d'entrée et de sortie, et le coût en dinars. Chaque ligne correspond à une requête réelle et porte son identifiant (X-Request-Id), ce qui permet de recouper avec vos propres journaux.

Le solde restant est aussi lisible par l'API :

curl https://api.cloudzir.com/v1/user/balance \
  -H "Authorization: Bearer $CLOUDZIR_API_KEY"

Voir Solde du compte.