Endpoint tokenize et outils

Compter les tokens avant d’envoyer

En production, vous devez pouvoir estimer le nombre de tokens d’une requête avant de l’envoyer à l’API. Cela vous permet de vérifier que votre prompt tient dans la fenêtre de contexte, d’anticiper le coût de la requête, et d’éviter les erreurs liées à un dépassement de la taille maximale. L’API Grok fournit un endpoint dédié à cette opération.

L’endpoint /v1/tokenize-text

L’endpoint POST /v1/tokenize-text accepte un texte brut et retourne le nombre de tokens correspondant. Contrairement à un appel de complétion, cet endpoint ne consomme pas de tokens facturés : il sert uniquement au comptage.

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 contient le nombre de tokens et, selon la version, la liste des tokens individuels. Utilisez cette information pour valider la taille de vos prompts avant de les envoyer au modèle.

Cas d’usage pratiques

• Validation de prompt : vérifiez que votre system prompt + historique + message utilisateur ne dépasse pas 2 millions de tokens
• Estimation de coût : multipliez le nombre de tokens par le tarif du modèle pour obtenir une estimation avant facturation
• Troncature intelligente : si un document est trop long, tokenisez-le pour trouver le point de coupure optimal

La console web de tokenisation

Pour les tests manuels et le prototypage, xAI met à disposition un outil de tokenisation visuel dans la console web. Accessible depuis la console xAI, cet outil permet de coller du texte et de voir instantanément le découpage en tokens.

Cet outil est particulièrement utile pour comprendre comment le tokenizer de Grok traite différents types de contenu :

• Le français génère généralement plus de tokens que l’anglais pour un même contenu sémantique
• Le code source est tokenisé différemment du texte naturel
• Les caractères spéciaux et la ponctuation peuvent consommer des tokens individuels

Intégrer le comptage dans votre pipeline

En production, n’appelez pas l’endpoint de tokenisation pour chaque requête : cela doublerait le nombre d’appels API. Utilisez-le plutôt de manière stratégique :

Approche par estimation

Pour les cas courants, estimez le nombre de tokens sans appeler l’API :

• Un mot français moyen correspond à environ 1,5 tokens
• Un caractère de code correspond à environ 0,3 tokens
• Une image correspond à 256-1 792 tokens selon sa taille

Approche par validation

Utilisez l’endpoint de tokenisation pour :

• Les prompts longs ou variables (documents utilisateur, RAG)
• La calibration initiale de vos templates de prompt
• Le debug lorsque vous recevez des erreurs de dépassement de contexte

Coûts des outils intégrés

Au-delà des tokens texte, l’API Grok propose des outils intégrés facturés à l’appel :

• Web Search : $5 pour 1 000 appels
• X Search : $5 pour 1 000 appels
• Code Execution : $5 pour 1 000 appels
• File Attachments : $10 pour 1 000 appels
• Collections Search : $2.50 pour 1 000 appels

Ces coûts s’ajoutent à la facturation par token. Dans un pipeline utilisant la recherche web à chaque requête, le coût des outils peut dépasser celui des tokens.

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 tokens par mot en moyenne