Endpoint tokenize et outils

Compter les tokens avant d’envoyer

Trois questions se posent avant chaque appel sérieux à l’API : mon prompt tient-il dans la fenêtre de contexte, combien va-t-il me coûter, et où couper si le document est trop long ? Y répondre après l’envoi, à la lecture d’une erreur ou d’une facture, revient toujours plus cher qu’y répondre avant. L’API Grok fournit précisément l’outil qu’il faut pour cela : un endpoint de tokenisation, gratuit et découplé des complétions.

L’endpoint /v1/tokenize-text

POST /v1/tokenize-text prend un texte brut et retourne le nombre de tokens correspondant. La caractéristique décisive tient en une phrase : contrairement à un appel de complétion, cet endpoint ne consomme aucun token facturé. Il compte, il ne génère rien.

curl -X POST "https://api.x.ai/v1/tokenize-text" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Votre texte à tokeniser ici."
  }'

La réponse vous donne le total de tokens et, selon la version, le détail des tokens individuels. Trois usages en découlent directement. La validation d’abord : vous vérifiez que la somme du prompt système, de l’historique et du message utilisateur reste dans la fenêtre du modèle visé, soit 1 million de tokens sur grok-4.3 et 500 000 sur grok-4.5. L’estimation de coût ensuite : le nombre obtenu, multiplié par le tarif du modèle, vous donne le prix de la requête avant de l’engager. La troncature enfin : sur un document trop volumineux, la tokenisation vous indique où couper proprement plutôt que de laisser l’API refuser l’ensemble.

L’outil visuel de la console

Pour le prototypage, xAI propose dans sa console web un tokenizer visuel où vous collez un texte et voyez immédiatement son découpage. C’est un excellent instrument pédagogique, à utiliser au moins une fois avant de concevoir vos templates de prompt.

Vous y ferez trois constats utiles. Le français produit sensiblement plus de tokens que l’anglais pour un contenu sémantiquement identique, ce qui pèse directement sur le coût d’une application francophone. Le code source est découpé selon une logique différente de celle du texte naturel. Et la ponctuation ou les caractères spéciaux occupent souvent un token à eux seuls — de quoi expliquer pourquoi un JSON verbeux coûte étonnamment cher à transmettre.

Où placer le comptage dans un pipeline

Attention au réflexe qui consiste à tokeniser systématiquement avant chaque appel : vous doublez le nombre de requêtes réseau et vous ajoutez une latence à chaque interaction, pour une information que vous connaissiez souvent d’avance. Le comptage exact se réserve aux cas où l’incertitude est réelle.

Pour tout le reste, une estimation suffit. Comptez environ 1,5 token par mot de français, environ 0,3 token par caractère de code, et de 256 à 1 792 tokens par image selon sa taille. Ces ordres de grandeur, appliqués côté client, vous permettent de rejeter localement un prompt manifestement hors gabarit sans consommer un appel.

Gardez alors l’endpoint pour trois situations : les prompts dont la taille varie fortement, typiquement les documents fournis par l’utilisateur ou les extraits remontés par un système RAG ; la calibration initiale de vos templates, quand vous établissez une fois pour toutes le budget de tokens de chaque brique ; et le débogage, lorsqu’une erreur de dépassement de contexte apparaît et qu’il faut identifier quel élément a gonflé.

Les outils intégrés, une ligne de facture à part

Les tokens ne sont pas la seule source de coût. Les outils intégrés à l’API sont facturés à l’appel, indépendamment du volume de texte échangé.

Faites le calcul sur votre propre trafic avant de généraliser un outil. Une application qui déclenche une recherche web à chaque requête paie $5 pour mille interactions au seul titre de l’outil, ce qui dépasse fréquemment le coût des tokens consommés sur la même période. La recherche web n’a rien de superflu, mais elle mérite d’être déclenchée sur condition plutôt que par défaut.

Points clés à retenir

• L’endpoint POST /v1/tokenize-text permet de compter les tokens sans facturation
• La console web de tokenisation est utile pour le prototypage et la compréhension du tokenizer
• N’appelez pas l’endpoint de tokenisation à chaque requête en production : utilisez des estimations
• Les outils intégrés (Web Search, Code Execution, etc.) ont des coûts additionnels par appel
• Le français consomme environ 1,5 token par mot en moyenne