如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

計算 Token 數量

在傳送請求前取得準確的輸入 Token 數量。

在將請求傳送給模型前,你可以先計算該請求會使用多少輸入 Token。這項功能可用來:

  • 最佳化提示詞,讓輸入符合上下文長度限制
  • 估算成本,在呼叫 API 前掌握費用
  • 依大小分派請求,例如將較短的提示詞傳送給速度較快的模型
  • 避免圖片和檔案的 Token 用量超出預期,無須再根據字元數估算

輸入 Token 計數端點接受的輸入格式與 Responses API 相同。傳入文字、訊息、圖片、檔案、工具或對話後,API 就會傳回模型實際收到的 Token 數量。

計數結果包含用來表示請求結構的格式 Token,例如標示訊息角色和訊息邊界的 Token。你在本機進行 Token 化的文字或欄位中,可能看不到這些 Token。

為什麼要使用 Token 計數 API?

tiktoken 等本機 Token 化工具適用於純文字,但有以下限制:

  • 圖片和檔案不在支援範圍內,使用 characters / 4 之類的公式估算並不準確
  • 工具和結構描述會增加 Token 數量,而這些 Token 很難在本機準確計算
  • 模型特有的行為(例如推理或快取)可能會影響 Token 化處理

Token 計數 API 可以處理上述所有情況。只要傳入與呼叫 responses.create 時相同的請求內容,就能取得準確的 Token 數量,再將結果用於訊息驗證或成本估算流程。

計算基本訊息的 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 數量

此 API 支援檔案輸入。請傳入 file_id、file_url 或 file_data,用法與呼叫 responses.create 時相同。計數結果涵蓋模型處理的完整輸入。

瞭解輸出 Token 數量

API 回報的輸出 Token 用量包含模型產生的所有 Token,包括回應中的可見文字。Responses API 透過 output_tokens 回報總數,Chat Completions API 則透過 completion_tokens 回報。

包括 GPT-5 系列模型在內的部分模型會產生 Token,用來設定回應通道、工具呼叫及其他訊息結構的格式,或標示其邊界。這些格式 Token 不會出現在訊息內容或 logprobs 中,用量明細也不一定會單獨列出。因此,API 回報的輸出或補全 Token 數量可能高於可見 Token 數量,也可能高於 logprobs 中的 Token 數量,即使回報的 reasoning_tokens 值為 0 也是如此。

max_output_tokens 和 max_completion_tokens 參數限制的是模型產生的 Token 總數,其中也包含不可見的 Token。不可見 Token 的數量會隨模型和回應結構而異,因此請勿假設回報用量與可見輸出的 Token 數量相差固定值。如果需要一定數量的可見輸出,請在設定這些上限時預留餘裕。

API 參考文件

如需完整的參數和回應結構,請參閱計算輸入 Token 數量的 API 參考文件。端點如下:

POST /v1/responses/input_tokens

回應包含 input_tokens(整數)和 object: "response.input_tokens"。