OpenAI API token 怎么计算？第三方指南与实操整理

更新于 2026-10-18 · gpt.boats

简答：OpenAI API token 是模型分词后统计的输入和输出单位，不能用字符数固定换算。请求完成后读取 usage；费用计算时，缓存 token 是输入 token 的子集，推理 token 是输出 token 的子集，不能重复相加。

定义：Token 是模型处理输入、生成输出以及部分消息结构时使用的计量单位，API 通常在 usage 中分别返回输入、输出、缓存和推理等统计字段。

OpenAI API token 到底按什么计算

OpenAI API token 不是“一个汉字等于一个 token”，也不是字符数除以固定数字。模型会对文字、空格、标点、消息角色、工具定义、图片和文件等内容进行分词或结构化处理，最终数量取决于具体模型和请求格式。

实际使用时可以分成两个问题：第一，请求已经完成后有多少 token，应读取响应里的 usage；第二，请求发送前预计有多少输入 token，可以使用官方 input token counting 接口。OpenAI 的 Token Counting 指南说明，该接口会按照模型实际接收的请求结构统计输入，并覆盖消息结构、工具、图片和文件等本地 tokenizer 不容易准确处理的内容。OpenAI Token Counting 官方指南

使用 Chat Completions 时，常见顶层字段是 prompt_tokens、completion_tokens 和 total_tokens；使用 Responses API 时，常见字段是 input_tokens、output_tokens 和 total_tokens。不同接口和模型的详细字段可能不同，应以实际响应及对应 API Reference 为准。OpenAI Chat Completions 创建接口OpenAI Responses API Reference

输入、输出、缓存和推理 token 的关系

Chat Completions 的详细统计路径通常是 usage.prompt_tokens_details.cached_tokens、usage.prompt_tokens_details.cache_write_tokens 和 usage.completion_tokens_details.reasoning_tokens。官方接口说明将 cached_tokens 定义为提示中的缓存 token，将 reasoning_tokens 定义为模型生成的推理 token。OpenAI Chat Completion usage 字段说明

因此，如果用户看到的回答很短，但 completion_tokens 或 output_tokens 较高，可能是输出统计包含了不可见的格式或结构 token，也可能包含推理模型使用的 reasoning_tokens。推理 token 仍然属于输出统计，不能因为用户看不到就从实际用量中删除。OpenAI Token Counting 官方指南

缓存 token 和推理 token 为什么不能重复计算

这是计算费用时最容易出错的地方。假设一次 Chat Completions 响应返回：

• prompt_tokens = 1200
• prompt_tokens_details.cached_tokens = 800
• completion_tokens = 300
• completion_tokens_details.reasoning_tokens = 100

这里不是把 1200、800、300、100 全部相加。正确理解是：1200 是全部输入 token，其中 800 个属于缓存输入；300 是全部输出 token，其中 100 个属于推理 token。缓存 token和推理 token分别是输入、输出的子集。

如果没有缓存写入费用，通用费用公式可以写成：

总费用 =（输入 token − 缓存 token）÷ 1,000,000 × 普通输入单价 + 缓存 token ÷ 1,000,000 × 缓存输入单价 + 输出 token ÷ 1,000,000 × 输出单价

如果接口返回了 cache_write_tokens，并且当前模型价格页单独列出缓存写入价格，则应进一步拆分：

普通输入 token = 输入 token − 缓存 token − 缓存写入 token

总费用 = 普通输入 token × 普通输入单价 + 缓存 token × 缓存输入单价 + 缓存写入 token × 缓存写入单价 + 输出 token × 输出单价

上述各项在公式中都要再除以 1,000,000。OpenAI 的提示缓存文档明确说明，缓存写入不是在普通输入费用上额外叠加，而是根据输入 token 属于普通输入、缓存输入或缓存写入类别分别计价；具体单价应以当前模型价格页为准。OpenAI Prompt Caching 官方指南OpenAI API 官方价格页

最小可运行示例：读取输入、缓存、输出和推理 token

下面示例使用 Python 3 标准库调用 Chat Completions，并打印常见 usage 字段。它不写死接口域名或模型名：BASE_URL 应设置为已经包含版本路径的基础地址，代码不会再次拼接 /v1；KEY 只从环境变量读取；MODEL_ID 应填写所用平台公开模型列表中的实际 ID。

依赖工具：Python 3，无需安装第三方 SDK。

export BASE_URL="https://api.openai.com/v1"
export KEY="your-api-key"
export MODEL_ID="以所用平台官方模型列表为准"

如果项目使用 .env 文件，可以写成：

BASE_URL=https://api.openai.com/v1
KEY=your-api-key
MODEL_ID=以所用平台官方模型列表为准

不要把密钥提交到代码仓库，在 .gitignore 中加入：

.env

保存为 read_usage.py 后运行：

import json
import os
import urllib.request

base_url = os.environ["BASE_URL"].rstrip("/")
api_key = os.environ["KEY"]
model_id = os.environ["MODEL_ID"]

payload = {
    "model": model_id,
    "messages": [
        {"role": "user", "content": "用一句话解释 token。"}
    ],
    "max_completion_tokens": 80,
}

request = urllib.request.Request(
    f"{base_url}/chat/completions",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request, timeout=60) as response:
    result = json.load(response)

usage = result.get("usage", {})
prompt_details = usage.get("prompt_tokens_details") or {}
completion_details = usage.get("completion_tokens_details") or {}

print("prompt_tokens:", usage.get("prompt_tokens"))
print("cached_tokens:", prompt_details.get("cached_tokens"))
print("cache_write_tokens:", prompt_details.get("cache_write_tokens"))
print("completion_tokens:", usage.get("completion_tokens"))
print("reasoning_tokens:", completion_details.get("reasoning_tokens"))
print("total_tokens:", usage.get("total_tokens"))
print("answer:", result["choices"][0]["message"]["content"])

成功响应通常应包含 choices 和 usage。某些兼容接口不返回缓存或推理细分字段，程序会打印 None，这不代表一定没有对应统计，只表示当前响应没有提供该字段。若接口或旧模型不接受 max_completion_tokens，可能返回参数错误；这时应查看该接口文档，确认是否需要改用 max_tokens，不要同时发送两个参数。OpenAI 官方 Chat Completions 示例展示了 prompt_tokens_details 和 completion_tokens_details 的返回结构。OpenAI Chat Completions 创建接口

import json
import os
import urllib.request

base_url = os.environ["BASE_URL"].rstrip("/")
api_key = os.environ["KEY"]
model_id = os.environ["MODEL_ID"]

payload = {
    "model": model_id,
    "input": [
        {
            "role": "user",
            "content": [
                {"type": "input_text", "text": "用一句话解释 token。"}
            ],
        }
    ],
}

request = urllib.request.Request(
    f"{base_url}/responses/input_tokens",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)

with urllib.request.urlopen(request, timeout=60) as response:
    result = json.load(response)

print("object:", result.get("object"))
print("input_tokens:", result["input_tokens"])