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
Theme

Contagem de tokens

Saiba exatamente quantos tokens de entrada cada requisição usará antes de enviá-la.

Com a contagem de tokens, você pode saber 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 à API
  • Encaminhar requisições conforme o tamanho (por exemplo, enviar prompts menores a modelos mais rápidos)
  • Evitar surpresas com imagens e arquivos, sem depender de estimativas baseadas no número de caracteres

O endpoint de contagem de tokens de entrada aceita o mesmo formato de entrada que a API Responses. Envie textos, mensagens, imagens, arquivos, ferramentas ou conversas. A API retorna o número exato de tokens que o modelo receberá.

A contagem inclui os tokens de formatação que representam a estrutura da requisição, como o papel de cada mensagem e os limites entre 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 algumas limitações:

  • Imagens e arquivos não são compatíveis com esses tokenizadores, e estimativas como characters / 4 são imprecisas
  • Ferramentas e schemas acrescentam tokens difíceis de contar localmente
  • Comportamentos específicos de cada modelo, como raciocínio e uso de cache, podem alterar a tokenização

A API de contagem de tokens leva todos esses fatores em conta. Para obter uma contagem precisa, envie os mesmos dados que você enviaria para responses.create. Depois, use o resultado para validar mensagens ou estimar 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 várias trocas de mensagens
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 em entradas com instruções

Entrada com instruções do 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 em entradas com imagens

O número de tokens que uma imagem consome depende do tamanho e do nível de detalhe da imagem. A API de contagem de tokens retorna a contagem exata, sem precisar de estimativas.

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 (obtido pela API Files) ou image_url (uma URL ou uma URL de dados em base64). Para mais detalhes, consulte o guia de imagens e visão.

Conte tokens em entradas com ferramentas

As definições de ferramentas, como schemas de funções e servidores MCP, acrescentam tokens ao contexto. Inclua esses tokens na contagem da entrada:

Entrada com ferramentas de chamada 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 em entradas com arquivos

A API aceita arquivos como entrada (atualmente, apenas PDFs). Envie file_id, file_url ou file_data como faria em uma chamada a responses.create. A contagem de tokens reflete toda a entrada que o modelo processa.

Entenda a contagem de tokens de saída

O uso de tokens de saída informado pela API inclui todos os tokens que o modelo gera, mesmo os que não aparecem no texto da resposta. A API Responses informa esse total em output_tokens, enquanto a API chat completions o informa em completion_tokens.

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

Os parâmetros max_output_tokens e max_completion_tokens limitam o total de tokens que o modelo gera, incluindo os que não ficam visíveis. A quantidade de tokens não visíveis varia conforme o modelo e o formato da resposta, por isso não presuma que a diferença entre o uso informado e a saída visível seja fixa. Ao definir esses limites, deixe uma margem quando precisar de uma quantidade específica de tokens visíveis na saída.

Referência da API

Para ver todos os parâmetros e o formato da resposta, consulte a referência da API de contagem de tokens de entrada. O endpoint é:

POST /v1/responses/input_tokens

A resposta inclui input_tokens (um número inteiro) e object: "response.input_tokens".