Token 计数可让你在将请求发送给模型之前，确定该请求将要消耗的输入 Token 数量。它可用于：
- 优化提示词 以适应上下文限制
- 估算成本 在进行 API 调用之前
- 路由请求 根据大小（例如，将较小的提示词路由到更快的模型）
- 避免意外情况 涉及图像和文件时——无需再使用基于字符的估算
The 输入 Token 计数端点 接受与以下对象相同的输入格式： Responses API。传入文本、消息、图像、文件、工具或对话——API 将返回模型接收到的准确 token 数量。
等本地分词器 tiktoken 适用于纯文本，但存在局限性：
- 图像和文件 不受支持——类似于
characters / 4 的估算并不准确
- 工具和 schemas 会增加难以在本地计数的 Token
- 特定模型的行为 可能会改变 Token 化方式（例如，推理、缓存）
Token 计数 API 可以处理所有这些问题。使用与发送给 responses.create 相同的负载，即可获得准确的计数。然后将结果应用到你的消息验证或成本估算流程中。
1
2
3
4
5
6
7
8
9
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5",
input="Tell me a joke."
)
print(response.input_tokens)
1
2
3
4
5
6
7
8
9
10
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5",
input: "Tell me a joke.",
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"input": "Tell me a joke."
}'
1
2
3
4
5
openai responses:input-tokens count \
--model gpt-5 \
--input "Tell me a joke." \
--raw-output \
--transform input_tokens
1
2
3
4
5
6
7
8
9
10
11
12
13
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5",
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
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5",
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
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"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
12
openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-5
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
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5",
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
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5",
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
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"instructions": "You are a helpful assistant that explains concepts simply.",
"input": "Explain quantum computing in one sentence."
}'
1
2
3
4
5
6
7
openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-5
instructions: You are a helpful assistant that explains concepts simply.
input: Explain quantum computing in one sentence.
YAML
图像根据其大小和细节层级消耗 Token。Token 计数 API 会返回确切的数值——无需猜测。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5",
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
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5",
input: [
{
role: "user",
content: [
{
type: "input_image",
image_url: "https://example.com/chart.png",
},
{ 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
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"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
12
openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-5
input:
- role: user
content:
- type: input_image
image_url: https://example.com/chart.png
- type: input_text
text: Summarize this chart.
YAML
你可以使用 file_id （来自 Files API) or image_url （URL 或 base64 数据 URL）。参见 图像与视觉 for details.
工具定义（函数 schemas、MCP 服务器等）会向上下文中添加 Token。将它们与你的输入一起计算：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
from openai import OpenAI
client = OpenAI()
response = client.responses.input_tokens.count(
model="gpt-5",
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
import OpenAI from "openai";
const client = new OpenAI();
const response = await client.responses.input_tokens.count({
model: "gpt-5",
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?",
});
console.log(response.input_tokens);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl https://api.openai.com/v1/responses/input_tokens \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-5",
"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
17
openai responses:input-tokens count \
--raw-output \
--transform input_tokens <<'YAML'
model: gpt-5
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
文件输入——目前支持 PDF。像传递给 file_id, file_url, or file_data 那样传入 responses.create。Token 数量反映了模型的完整处理输入。
有关完整的参数和响应结构，请参见 计算输入 Token API 参考。端点为：
POST /v1/responses/input_tokens
The response includes input_tokens （整数）和 object: "response.input_tokens".
