For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navigation principale
Theme

Comptage des tokens

Obtenez le nombre exact de tokens d’entrée avant d’envoyer vos requêtes.

Le comptage des tokens vous permet de connaître le nombre de tokens d’entrée qu’une requête utilisera avant de l’envoyer au modèle. Vous pouvez ainsi :

  • Optimiser vos prompts pour respecter les limites de la fenêtre de contexte
  • Estimer les coûts avant d’appeler l’API
  • Acheminer les requêtes selon leur taille (par exemple, envoyer les prompts les plus courts aux modèles les plus rapides)
  • Éviter les surprises avec les images et les fichiers, sans avoir à estimer le nombre de tokens à partir du nombre de caractères

Le point de terminaison de comptage des tokens d’entrée accepte le même format d’entrée que l’API Responses. Fournissez du texte, des messages, des images, des fichiers, des outils ou des conversations. L’API renvoie le nombre exact de tokens que le modèle recevra.

Le décompte inclut les tokens de formatage qui représentent la structure de la requête. Ils indiquent notamment le rôle de chaque message et en délimitent le contenu. Ces tokens peuvent ne pas apparaître dans le texte ou les champs que vous tokenisez localement.

Pourquoi utiliser l’API de comptage des tokens ?

Les tokeniseurs locaux comme tiktoken conviennent au texte brut, mais présentent certaines limites :

  • Les images et les fichiers ne sont pas pris en charge. Les estimations comme characters / 4 manquent de précision.
  • Les outils et les schémas ajoutent des tokens difficiles à compter localement.
  • Les comportements propres à chaque modèle peuvent modifier la tokenisation (par exemple, le raisonnement ou la mise en cache).

L’API de comptage des tokens prend en charge tous ces cas. Envoyez-lui le même contenu que vous enverriez à responses.create pour obtenir un décompte exact. Utilisez ensuite ce résultat pour valider vos messages ou estimer vos coûts.

Compter les tokens dans des messages simples

Texte simple en entrée
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra", input="Tell me a joke."
)
print(response.input_tokens)

Compter les tokens dans une conversation

Conversation en plusieurs échanges
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    input=[
        {"role": "user", "content": "What is 2 + 2?"},
        {"role": "assistant", "content": "2 + 2 equals 4."},
        {"role": "user", "content": "What about 3 + 3?"},
    ],
)
print(response.input_tokens)

Compter les tokens d’une entrée contenant des instructions

Entrée avec des instructions système
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    instructions="You are a helpful assistant that explains concepts simply.",
    input="Explain quantum computing in one sentence.",
)
print(response.input_tokens)

Compter les tokens d’une entrée contenant des images

Le nombre de tokens consommés par une image dépend de sa taille et du niveau de détail. L’API de comptage des tokens renvoie le nombre exact, sans estimation.

Entrée avec une image
from openai import OpenAI

client = OpenAI()

# Use file_id from uploaded file, or image_url for a URL
response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    input=[
        {
            "role": "user",
            "content": [
                {
                    "type": "input_image",
                    "image_url": "https://example.com/chart.png",
                },
                {"type": "input_text", "text": "Summarize this chart."},
            ],
        }
    ],
)
print(response.input_tokens)

Vous pouvez utiliser file_id (fourni par l’API Files) ou image_url (une URL ou une URL de données en base64). Pour en savoir plus, consultez le guide sur les images et la vision.

Compter les tokens d’une requête qui utilise des outils

Les définitions d’outils (schémas de fonctions, serveurs MCP, etc.) ajoutent des tokens au contexte. Comptez-les en même temps que ceux de votre entrée :

Entrée avec des outils de type fonction
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6-astra",
    tools=[
        {
            "type": "function",
            "name": "get_weather",
            "description": "Get the current weather in a location",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        }
    ],
    input="What is the weather in San Francisco?",
)
print(response.input_tokens)

Compter les tokens d’une entrée contenant des fichiers

L’API accepte les fichiers en entrée (actuellement au format PDF uniquement). Fournissez file_id, file_url ou file_data comme vous le feriez pour responses.create. Le décompte tient compte de l’intégralité de l’entrée que traite le modèle.

Comprendre le décompte des tokens de sortie

Le décompte des tokens de sortie inclut tous les tokens générés par le modèle, y compris ceux qui n’apparaissent pas dans le texte de la réponse. L’API Responses indique ce total dans output_tokens et l’API Chat Completions dans completion_tokens.

Certains modèles, dont les modèles GPT-5, génèrent des tokens pour mettre en forme ou délimiter les canaux de réponse, les appels d’outils et d’autres éléments de la structure des messages. Ces tokens de formatage n’apparaissent ni dans le contenu du message ni dans logprobs. Les statistiques d’utilisation ne les détaillent pas systématiquement. Le nombre de tokens de sortie ou de complétion indiqué peut donc dépasser le nombre de tokens visibles ou de tokens inclus dans logprobs, même lorsque la valeur indiquée pour reasoning_tokens est 0.

Les paramètres max_output_tokens et max_completion_tokens limitent le nombre total de tokens générés par le modèle, y compris les tokens invisibles. Le nombre de tokens invisibles varie selon le modèle et la structure de la réponse. Ne supposez donc pas que l’écart entre le décompte indiqué et le nombre de tokens visibles est constant. Si vous avez besoin d’une quantité précise de contenu visible, prévoyez une marge lorsque vous fixez ces limites.

Référence de l’API

Pour connaître tous les paramètres et la structure de la réponse, consultez la référence de l’API de comptage des tokens d’entrée. Utilisez le point de terminaison suivant :

POST /v1/responses/input_tokens

La réponse contient input_tokens (un entier) et object: "response.input_tokens".