如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

统计 Token 数量

在发送请求前获取准确的输入 Token 数量。

在向模型发送请求前,您可以先统计该请求将使用多少个输入 Token。这有助于您:

  • 优化提示,使其符合上下文长度限制
  • 估算费用,在调用 API 前了解预计成本
  • 按大小路由请求,例如将较短的提示发送给速度更快的模型
  • 避免用量超出预期,直接统计图像和文件的 Token 数量,无需按字符数估算

输入 Token 计数端点接受与 Responses API 相同的输入格式。您可以传入文本、消息、图像、文件、工具或对话,API 会返回模型将收到的确切 Token 数量。

计数包括用于表示请求结构的格式 Token,例如标记消息角色和消息边界的 Token。您在本地对文本或字段进行 Token 化时,可能看不到这些 Token。

为什么使用 Token 计数 API?

tiktoken 等本地分词器可以处理纯文本,但存在以下限制:

  • 图像和文件不受支持,使用 characters / 4 等方法估算也不准确
  • 工具和模式定义会引入额外的 Token,在本地很难准确统计
  • 模型特有的行为(例如推理和缓存)可能影响 Token 化处理

Token 计数 API 可以处理上述所有情况。您只需传入与调用 responses.create 时相同的请求体,即可获得准确的 Token 数量,再将结果用于消息验证或费用估算。

统计简单消息中的 Token

简单文本输入
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6.2-astra", input="Tell me a joke."
)
print(response.input_tokens)

统计对话中的 Token

多轮对话
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6.2-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)

统计包含指令的输入 Token 数量

包含系统指令的输入
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6.2-astra",
    instructions="You are a helpful assistant that explains concepts simply.",
    input="Explain quantum computing in one sentence.",
)
print(response.input_tokens)

统计包含图像的输入 Token 数量

图像消耗的 Token 数量取决于图像大小和细节级别。Token 计数 API 会返回确切数量,无需估算。

包含图像的输入
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.2-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)

您可以使用 file_id(通过 Files API 获取)或 image_url(URL 或 base64 数据 URL)。详情请参阅图像与视觉。

统计包含工具的输入 Token 数量

工具定义(例如函数模式和 MCP 服务器定义)会占用上下文中的 Token。您可以将工具定义与其他输入一起统计:

包含函数工具的输入
from openai import OpenAI

client = OpenAI()

response = client.responses.input_tokens.count(
    model="gpt-6.2-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)

统计包含文件的输入 Token 数量

API 支持文件输入。请通过 file_id、file_url 或 file_data 传入文件,用法与调用 responses.create 时相同。Token 计数反映了模型处理后的完整输入。

理解输出 Token 数量

API 报告的输出 Token 用量涵盖模型生成的所有 Token,包括响应中可见文本之外的 Token。Responses API 通过 output_tokens 报告总数,Chat Completions API 则通过 completion_tokens 报告总数。

包括 GPT-5 系列在内的一些模型会生成格式 Token,用来表示响应通道、工具调用及其他消息结构的格式或边界。这些格式 Token 不会出现在消息内容或 logprobs 中,用量统计也不一定会单独列出它们。因此,报告的输出或补全 Token 数量可能多于可见的 Token 数量或 logprobs 中包含的 Token 数量,即使报告的 reasoning_tokens 值为 0 也可能如此。

max_output_tokens 和 max_completion_tokens 参数限制模型生成的 Token 总数,其中包括不可见的 Token。不可见的 Token 数量随模型和响应结构而变化,因此请勿假设报告的用量与可见输出之间存在固定差值。如果您需要一定数量的可见输出,请在设置这些上限时留出余量。

API 参考

有关完整的参数列表和响应结构,请参阅输入 Token 计数 API 参考。端点如下:

POST /v1/responses/input_tokens

响应包含 input_tokens(整数)和 object: "response.input_tokens"。