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

Comptage des tokens

Obtenez un décompte précis des tokens d’entrée avant d’envoyer vos requêtes.

Le comptage des tokens vous permet de déterminer combien de tokens d’entrée une requête utilisera avant de l’envoyer au modèle. Utilisez-le pour :

  • Optimiser les prompts pour respecter les limites de contexte
  • Estimer les coûts avant d’effectuer des appels API
  • Acheminez les requêtes en fonction de leur taille (par exemple, les prompts plus courts vers des modèles plus rapides)
  • Éviter les surprises avec les images et les fichiers : plus besoin d’estimations basées sur le 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, comme les rôles et les délimitations des messages. 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 outils de tokenisation locaux comme tiktoken fonctionnent pour le texte brut, mais présentent des limites :

  • Les images et les fichiers ne sont pas pris en charge : les estimations comme characters / 4 sont imprécises
  • Les outils et les schémas ajoutent des tokens difficiles à compter localement
  • Les comportements propres au 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. Utilisez les mêmes données que vous enverriez à responses.create pour obtenir un décompte précis. Intégrez ensuite le résultat à votre workflow de validation des messages ou d’estimation des coûts.

Comptez les tokens dans des messages simples

Entrée de texte simple
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)

Comptez les tokens dans des conversations

Conversation à plusieurs tours
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)

Comptez les tokens avec 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)

Comptez les tokens avec des images

Les images consomment des tokens en fonction de leur taille et de leur niveau de détail. L’API de comptage des tokens renvoie un décompte exact, sans approximation.

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 (provenant de l’API Files) ou image_url (une URL ou une URL de données en base64). Consultez le guide Images et vision pour en savoir plus.

Comptez les tokens avec des outils

Les définitions d’outils (schémas de fonctions, serveurs MCP, etc.) ajoutent des tokens au contexte. Comptez-les avec ceux de vos données d’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)

Comptez les tokens avec des fichiers

Les fichiers en entrée (actuellement les PDF) sont pris en charge. Fournissez file_id, file_url ou file_data comme vous le feriez pour responses.create. Le décompte des tokens tient compte de l’intégralité des données d’entrée du modèle après traitement.

Comprenez le décompte des tokens de sortie

La consommation de tokens de sortie indiquée inclut tous les tokens générés par le modèle, et pas seulement le texte visible dans une réponse. L’API Responses indique ce total dans output_tokens, tandis que l’API Chat Completions l’indique dans completion_tokens.

Certains modèles, dont les modèles GPT-5, génèrent des tokens servant à formater ou à délimiter les canaux de réponse, les appels d’outils et d’autres éléments de structure des messages. Ces tokens de formatage n’apparaissent ni dans le contenu des messages ni dans logprobs, et ne sont pas nécessairement détaillés séparément dans les données de consommation. Par conséquent, le nombre de tokens de sortie ou de complétion indiqué peut être supérieur au 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 l’ensemble des tokens générés par le modèle, y compris les tokens non visibles. Le nombre de tokens non visibles varie selon le modèle et la structure de la réponse : ne supposez donc pas que l’écart entre la consommation indiquée et la sortie visible est fixe. Prévoyez une marge dans ces limites lorsque vous avez besoin d’une quantité précise de contenu visible en sortie.

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. Le point de terminaison est le suivant :

POST /v1/responses/input_tokens

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