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

Token zählen

Ermittle die genaue Anzahl der Eingabetoken, bevor du Anfragen sendest.

Mit der Tokenzählung ermittelst du, wie viele Eingabetoken eine Anfrage benötigt, bevor du sie an das Modell sendest. Damit kannst du:

  • Prompts optimieren , damit sie die Kontextgrenzen einhalten
  • Kosten abschätzen , bevor du API-Aufrufe ausführst
  • Anfragen weiterleiten , je nach Umfang (zum Beispiel kürzere Prompts an schnellere Modelle)
  • Überraschungen vermeiden , wenn du Bilder und Dateien verwendest, ohne auf Schätzungen anhand der Zeichenzahl angewiesen zu sein

Der Endpunkt zum Zählen von Eingabetoken akzeptiert dasselbe Eingabeformat wie die Responses API. Übergib Text, Nachrichten, Bilder, Dateien, Werkzeuge oder Unterhaltungen. Die API gibt die genaue Anzahl der Token zurück, die das Modell erhält.

Die Zählung umfasst auch Formatierungstoken, die die Struktur der Anfrage abbilden, etwa Nachrichtenrollen und Nachrichtengrenzen. Diese Token sind möglicherweise nicht in den Texten oder Feldern enthalten, die du lokal tokenisierst.

Warum die API zur Tokenzählung verwenden?

Lokale Tokenizer wie tiktoken funktionieren für reinen Text, haben aber Einschränkungen:

  • Bilder und Dateien werden nicht unterstützt. Schätzungen wie characters / 4 sind ungenau
  • Tools und Schemas fügen Token hinzu, die sich lokal nur schwer zählen lassen
  • Modellspezifisches Verhalten kann die Tokenisierung verändern (zum Beispiel Reasoning-Aufwand oder Caching)

Die API zur Tokenzählung berücksichtigt all diese Fälle. Verwende dieselbe Nutzlast, die du an responses.create senden würdest, um eine genaue Anzahl zu erhalten. Nutze das Ergebnis anschließend zur Validierung deiner Nachrichten oder zur Kostenschätzung.

Token in einfachen Nachrichten zählen

Einfache Texteingabe
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 in Unterhaltungen zählen

Unterhaltung mit mehreren Gesprächsrunden
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 bei Eingaben mit Anweisungen zählen

Eingabe mit Systemanweisungen
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 bei Eingaben mit Bildern zählen

Wie viele Token Bilder verbrauchen, hängt von ihrer Größe und Detailstufe ab. Die API zur Tokenzählung liefert die genaue Anzahl, ganz ohne Schätzungen.

Eingabe mit einem Bild
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)

Du kannst file_id (aus der Files API) oder image_url (eine URL oder eine Base64-Daten-URL) verwenden. Weitere Informationen findest du unter Bilder und Bildverständnis.

Token bei Eingaben mit Tools zählen

Tool-Definitionen (Funktionsschemas, MCP-Server usw.) fügen dem Kontext Token hinzu. Zähle sie zusammen mit deiner Eingabe:

Eingabe mit Funktions-Tools
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 bei Eingaben mit Dateien zählen

Dateieingaben (derzeit PDFs) werden unterstützt. Übergib file_id, file_url oder file_data wie bei responses.create. Die Tokenanzahl entspricht der gesamten für das Modell aufbereiteten Eingabe.

Die Anzahl der Ausgabetoken verstehen

Der gemeldete Verbrauch an Ausgabetoken umfasst alle vom Modell generierten Token, nicht nur den sichtbaren Text einer Antwort. Die Responses API meldet diese Gesamtzahl als output_tokens, die Chat Completions API als completion_tokens.

Einige Modelle, darunter GPT-5-Modelle, generieren Token, um Antwortkanäle, Tool-Aufrufe und andere Bestandteile der Nachrichtenstruktur zu formatieren oder voneinander abzugrenzen. Diese Formatierungstoken erscheinen weder im Nachrichteninhalt noch in logprobs und werden in den Verbrauchsangaben nicht unbedingt separat ausgewiesen. Daher kann die gemeldete Anzahl der Ausgabe- oder Completion-Token höher sein als die Anzahl der sichtbaren oder in logprobs enthaltenen Token, selbst wenn der gemeldete Wert für reasoning_tokens bei 0 liegt.

Die Parameter max_output_tokens und max_completion_tokens begrenzen die Gesamtzahl aller vom Modell generierten Token, einschließlich der nicht sichtbaren Token. Die Anzahl der nicht sichtbaren Token variiert je nach Modell und Antwortstruktur. Gehe deshalb nicht von einer festen Differenz zwischen dem gemeldeten Verbrauch und der sichtbaren Ausgabe aus. Plane bei diesen Grenzen einen Puffer ein, wenn du eine bestimmte Menge an sichtbarer Ausgabe benötigst.

API-Referenz

Alle Parameter und die Antwortstruktur findest du in der API-Referenz zum Zählen von Eingabetoken. Der Endpunkt lautet:

POST /v1/responses/input_tokens

Die Antwort enthält input_tokens (Ganzzahl) und object: "response.input_tokens".