For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
主导航

建议

开始使用

核心概念

SDK 与 CLI

资源

旧版 API

API Dashboard
试用 ChatGPT

Token 计数

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

Token 计数让您在向模型发送请求之前，就能确定请求将使用多少输入 Token。您可以用它来：

  • 优化提示 ，使其符合上下文限制
  • 在调用 API 之前估算费用
  • 根据请求大小路由请求 （例如，将较短的提示发送给速度更快的模型）
  • 处理图像和文件时避免用量超出预期 ，不再依赖基于字符数的估算

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

计数包含用于表示请求结构的格式 Token，例如用于标识消息角色和边界的 Token。这些 Token 可能不会出现在您在本地进行 Token 化处理的文本或字段中。

为什么使用 Token 计数 API？

tiktoken 等本地 Token 化工具适用于纯文本，但存在以下局限：

  • 不支持图像和文件 ，使用 characters / 4 等方式估算并不准确
  • 工具和模式 会增加难以在本地统计的 Token
  • 模型特有的行为 （例如推理、缓存）可能改变 Token 化处理方式

Token 计数 API 可以处理所有这些情况。使用您原本要发送给 responses.create 的相同请求数据，即可获得准确的计数。然后将结果用于您的消息验证或费用估算流程。

统计基本消息的 Token 数量

简单文本输入
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)

统计对话的 Token 数量

多轮对话
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)

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

包含系统指令的输入
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)

统计包含图像的输入的 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-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-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 数量

支持文件输入（目前支持 PDF）。请按照调用 responses.create 时的方式传入 file_id、file_url 或 file_data。Token 计数涵盖模型处理后的完整输入。

了解输出 Token 计数

报告的输出 Token 用量包含模型生成的所有 Token，而不仅仅是响应中的可见文本。Responses API 通过 output_tokens 报告这一总数，Chat Completions API 则通过 completion_tokens 报告。

包括 GPT-5 模型在内的某些模型会生成用于格式化或分隔响应通道、工具调用及其他消息结构的 Token。这些格式 Token 不会出现在消息内容或 logprobs 中，也不一定会在用量中单独列出。因此，即使报告的 reasoning_tokens 值为 0，报告的输出或补全 Token 数量也可能高于可见 Token 数量或 logprobs 中包含的 Token 数量。

max_output_tokens 和 max_completion_tokens 参数限制的是模型生成的所有 Token 的总量，包括不可见的 Token。不可见 Token 的数量会因模型和响应结构而异，因此请勿假定报告用量与可见输出之间存在固定差值。当您需要特定数量的可见输出时，请在设置这些限制时预留余量。

API 参考

有关完整的参数说明和响应结构，请参阅输入 Token 计数 API 参考。端点如下：

POST /v1/responses/input_tokens

响应包含 input_tokens（整数）和 object: "response.input_tokens"。