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.
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.
1
2
3
4
5
6
7
8
9
10import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
input: "Tell me a joke.",
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-6-astra", input="Tell me a joke."
)
print(response.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Input: responses.InputTokenCountParamsInputUnion{OfString: openai.String("Tell me a joke.")},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.input("Tell me a joke.")
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10require "openai"
client = OpenAI::Client.new
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
input: "Tell me a joke."
)
puts(count.input_tokens)
1
2
3
4
5
6
7curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"input": "Tell me a joke."
}'
1
2
3
4
5openai responses:input-tokens count \
--model gpt-6-astra \
--input "Tell me a joke." \
--raw-output \
--transform input_tokens
1
2
3
4
5
6
7
8
9
10
11
12
13
14import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.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?" },
],
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10
11
12
13from 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
input := []responses.ResponseInputItemUnionParam{
responses.ResponseInputItemParamOfMessage("What is 2 + 2?", responses.EasyInputMessageRoleUser),
responses.ResponseInputItemParamOfMessage("2 + 2 equals 4.", responses.EasyInputMessageRoleAssistant),
responses.ResponseInputItemParamOfMessage("What about 3 + 3?", responses.EasyInputMessageRoleUser),
}
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Input: responses.InputTokenCountParamsInputUnion{OfResponseInputItemArray: input},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.ResponseInputItem;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
import java.util.List;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.inputOfResponseInputItems(
List.of(
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("What is 2 + 2?")
.build()),
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.ASSISTANT)
.content("2 + 2 equals 4.")
.build()),
ResponseInputItem.ofEasyInputMessage(
EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("What about 3 + 3?")
.build())))
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"
client = OpenAI::Client.new
conversation = [
{
role: :user,
content: "What is 2 + 2?"
},
{
role: :assistant,
content: "2 + 2 equals 4."
},
{
role: :user,
content: "What about 3 + 3?"
}
]
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
input: conversation
)
puts(count.input_tokens)
1
2
3
4
5
6
7
8
9
10
11curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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?"}
]
}'
1
2
3
4
5
6
7
8
9
10
11
12openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
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?
YAML
1
2
3
4
5
6
7
8
9
10
11import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
instructions: "You are a helpful assistant that explains concepts simply.",
input: "Explain quantum computing in one sentence.",
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10from 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("You are a helpful assistant that explains concepts simply."),
Input: responses.InputTokenCountParamsInputUnion{OfString: openai.String("Explain quantum computing in one sentence.")},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.input("Explain quantum computing in one sentence.")
.instructions("You are a helpful assistant that explains concepts simply.")
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10
11require "openai"
client = OpenAI::Client.new
count = 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."
)
puts(count.input_tokens)
1
2
3
4
5
6
7
8curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-6-astra",
"instructions": "You are a helpful assistant that explains concepts simply.",
"input": "Explain quantum computing in one sentence."
}'
1
2
3
4
5
6
7openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-6-astra
instructions: You are a helpful assistant that explains concepts simply.
input: Explain quantum computing in one sentence.
YAML
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
input: [
{
role: "user",
content: [
{
type: "input_image",
image_url: "https://example.com/chart.png",
detail: "auto",
},
{ type: "input_text", text: "Summarize this chart." },
],
},
],
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
input := []responses.ResponseInputItemUnionParam{
responses.ResponseInputItemParamOfMessage(
responses.ResponseInputMessageContentListParam{
{OfInputImage: &responses.ResponseInputImageParam{ImageURL: openai.String("https://example.com/chart.png"), Detail: responses.ResponseInputImageDetailAuto}},
{OfInputText: &responses.ResponseInputTextParam{Text: "Summarize this chart."}},
},
responses.EasyInputMessageRoleUser,
),
}
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Input: responses.InputTokenCountParamsInputUnion{OfResponseInputItemArray: input},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.ResponseInputImage;
import com.openai.models.responses.ResponseInputItem;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
import java.util.List;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.inputOfResponseInputItems(
List.of(
ResponseInputItem.ofMessage(
ResponseInputItem.Message.builder()
.role(ResponseInputItem.Message.Role.USER)
.addContent(
ResponseInputImage.builder()
.detail(ResponseInputImage.Detail.AUTO)
.imageUrl(
"https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg")
.build())
.addInputTextContent("Summarize this chart.")
.build())))
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25require "openai"
client = OpenAI::Client.new
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
input: [
{
role: :user,
content: [
{
type: :input_image,
image_url: "https://api.nga.gov/iiif/a2e6da57-3cd1-4235-b20e-95dcaefed6c8/full/!800,800/0/default.jpg",
detail: :auto
},
{
type: :input_text,
text: "Summarize this chart."
}
]
}
]
)
puts(count.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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."}
]
}]
}'
1
2
3
4
5
6
7
8
9
10
11
12openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
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.
YAML
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.
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:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.inputTokens.count({
model: "gpt-6-astra",
tools: [
{
type: "function",
name: "get_weather",
description: "Get the current weather in a location",
strict: true,
parameters: {
type: "object",
properties: { location: { type: "string" } },
required: ["location"],
additionalProperties: false,
},
},
],
input: "What is the weather in San Francisco?",
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21from 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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32package main
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/responses"
)
func main() {
client := openai.NewClient()
parameters := map[string]any{
"type": "object",
"properties": map[string]any{
"location": map[string]any{"type": "string"},
},
"required": []string{"location"},
"additionalProperties": false,
}
tool := responses.ToolParamOfFunction("get_weather", parameters, true)
tool.OfFunction.Description = openai.String("Get the current weather in a location")
count, err := client.Responses.InputTokens.Count(context.Background(), responses.InputTokenCountParams{
Model: openai.String("gpt-6-astra"),
Input: responses.InputTokenCountParamsInputUnion{OfString: openai.String("What is the weather in San Francisco?")},
Tools: []responses.ToolUnionParam{tool},
})
if err != nil {
panic(err)
}
fmt.Println(count.InputTokens)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.core.JsonValue;
import com.openai.models.responses.FunctionTool;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
import java.util.List;
import java.util.Map;
var count =
client
.responses()
.inputTokens()
.count(
InputTokenCountParams.builder()
.model("gpt-6-astra")
.input("What is the weather in San Francisco?")
.addTool(
FunctionTool.builder()
.name("get_weather")
.description("Get the current weather in a location")
.strict(true)
.parameters(
FunctionTool.Parameters.builder()
.putAdditionalProperty("type", JsonValue.from("object"))
.putAdditionalProperty(
"properties",
JsonValue.from(
Map.of("location", Map.of("type", "string"))))
.putAdditionalProperty(
"required", JsonValue.from(List.of("location")))
.putAdditionalProperty(
"additionalProperties", JsonValue.from(false))
.build())
.build())
.build());
System.out.println(count.inputTokens());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24require "openai"
client = OpenAI::Client.new
count = client.responses.input_tokens.count(
model: "gpt-6-astra",
input: "What is the weather in San Francisco?",
tools: [
{
type: :function,
name: "get_weather",
description: "Get the current weather in a location",
strict: true,
parameters: {
type: "object",
properties: { location: { type: "string" } },
required: ["location"],
additionalProperties: false
}
}
]
)
puts(count.input_tokens)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"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?"
}'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
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?
YAML
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.
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.
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".