For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Navegação principal

Contagem de tokens

Obtenha contagens precisas de tokens de entrada antes de enviar requisições.

A contagem de tokens permite determinar quantos tokens de entrada uma requisição usará antes de enviá-la ao modelo. Use esse recurso para:

  • Otimizar prompts para que caibam nos limites de contexto
  • Estimar custos antes de fazer chamadas de API
  • Encaminhar requisições com base no tamanho (por exemplo, prompts menores para modelos mais rápidos)
  • Evitar surpresas com imagens e arquivos, sem precisar de estimativas baseadas em caracteres

O endpoint de contagem de tokens de entrada aceita o mesmo formato de entrada que a API Responses. Envie texto, mensagens, imagens, arquivos, ferramentas ou conversas: a API retorna a quantidade exata de tokens que o modelo receberá.

A contagem inclui tokens de formatação usados para representar a estrutura da requisição, como papéis e delimitadores de mensagens. Esses tokens podem não aparecer no texto ou nos campos que você tokeniza localmente.

Por que usar a API de contagem de tokens?

Tokenizadores locais, como o tiktoken, funcionam para texto simples, mas têm limitações:

  • Imagens e arquivos não são compatíveis; estimativas como characters / 4 são imprecisas
  • Ferramentas e esquemas adicionam tokens difíceis de contar localmente
  • Comportamentos específicos de cada modelo podem alterar a tokenização (por exemplo, raciocínio e armazenamento em cache)

A API de contagem de tokens lida com todos esses casos. Use o mesmo payload que enviaria para responses.create e obtenha uma contagem precisa. Depois, incorpore o resultado ao seu fluxo de validação de mensagens ou estimativa de custos.

Conte tokens em mensagens básicas

Entrada de texto simples
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)

Conte tokens em conversas

Conversa com múltiplos turnos
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)

Conte tokens com instruções

Entrada com instruções de sistema
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)

Conte tokens com imagens

As imagens consomem tokens de acordo com o tamanho e o nível de detalhe. A API de contagem de tokens retorna a contagem exata, sem suposições.

Entrada com uma imagem
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)

Você pode usar file_id (da Files API) ou image_url (uma URL ou uma URL de dados em base64). Consulte imagens e visão para saber mais.

Conte tokens com ferramentas

As definições de ferramentas (esquemas de funções, servidores MCP etc.) adicionam tokens ao contexto. Conte esses tokens junto com os da sua entrada:

Entrada com ferramentas de função
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)

Conte tokens com arquivos

Há suporte a arquivos de entrada (atualmente PDFs). Passe file_id, file_url ou file_data como faria para responses.create. A contagem de tokens reflete toda a entrada processada pelo modelo.

Entenda a contagem de tokens de saída

O uso informado de tokens de saída inclui todos os tokens gerados pelo modelo, não apenas o texto visível na resposta. A Responses API informa esse total em output_tokens, enquanto a API chat completions o informa em completion_tokens.

Alguns modelos, incluindo os modelos GPT-5, geram tokens usados para formatar ou delimitar canais de resposta, chamadas de ferramentas e outros elementos da estrutura das mensagens. Esses tokens de formatação não aparecem no conteúdo das mensagens nem em logprobs, e nem sempre são discriminados separadamente nos dados de uso. Por isso, a contagem informada de tokens de saída ou de conclusão pode ser maior que o número de tokens visíveis ou de tokens incluídos em logprobs, mesmo quando o valor informado de reasoning_tokens é 0.

Os parâmetros max_output_tokens e max_completion_tokens limitam todos os tokens gerados pelo modelo, incluindo os tokens não visíveis. A quantidade de tokens não visíveis varia conforme o modelo e a estrutura da resposta, portanto, não presuma uma diferença fixa entre o uso informado e a saída visível. Deixe uma margem nesses limites quando precisar de uma quantidade específica de saída visível.

Referência da API

Para consultar todos os parâmetros e a estrutura da resposta, veja a referência da API de contagem de tokens de entrada. O endpoint é:

POST /v1/responses/input_tokens

A resposta inclui input_tokens (inteiro) e object: "response.input_tokens".