> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sunra.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Token-Nutzung
Jede LLM-Antwort enthält ein `usage`-Objekt, das die von der Anfrage verbrauchten Tokens ausweist. Sunra meldet die Nutzung in der Semantik des Endpoints, den Sie aufgerufen haben: Eine Messages-Antwort folgt dem Anthropic-Kontrakt, und eine Chat Completions- oder Responses-Antwort folgt dem OpenAI-Kontrakt.
Diese Formen unterscheiden sich – und zwar bewusst. Ein OpenAI SDK, das eine Chat Completions-Antwort liest, setzt OpenAI-Semantik voraus, und ein Anthropic SDK, das eine Messages-Antwort liest, setzt Anthropic-Semantik voraus. Jeder Endpoint hält das ein, was seine eigene Spezifikation zusagt, anstatt in eine gemeinsame Form gezwungen zu werden.
| Endpoint | Feld für die Prompt-Zählung | Sind gecachte Tokens darin enthalten? |
| ---------------------- | --------------------------- | ------------------------------------------------------------------------------------ |
| `/v1/messages` | `input_tokens` | Nein – die drei Eingabe-Buckets schließen sich gegenseitig aus |
| `/v1/chat/completions` | `prompt_tokens` | Ja – gecachte Tokens sind eine Teilmenge, aufgeschlüsselt in `prompt_tokens_details` |
| `/v1/responses` | `input_tokens` | Ja – gecachte Tokens sind eine Teilmenge, aufgeschlüsselt in `input_tokens_details` |
`/v1/messages` und `/v1/responses` verwenden beide den Feldnamen `input_tokens`, und er bedeutet in beiden Fällen nicht dasselbe. Bei Messages ist es ausschließlich frische Eingabe. Bei Responses ist es der gesamte Prompt, einschließlich der gecachten Tokens.
## Messages
Auf `/v1/messages` schließen sich die drei Eingabe-Buckets **gegenseitig aus**. Kein Token wird doppelt gezählt, daher ist die Prompt-Gesamtsumme ihre Summe:
```
total prompt = input_tokens + cache_creation_input_tokens + cache_read_input_tokens
```
Nur frische Eingabe-Tokens. Schließt beide Cache-Buckets aus.
Tokens, die von dieser Anfrage in den Cache geschrieben wurden.
Tokens, die dieser Anfrage aus dem Cache bereitgestellt wurden.
Vom Modell generierte Tokens.
Die drei Eingabe-Buckets plus `output_tokens`. Vorhanden bei nicht gestreamten Antworten.
Ein Bucket, der fehlt oder `null` ist, zählt als null.
### Durchgerechnetes Beispiel
Dasselbe Präfix mit 19.000 Tokens wird zweimal an `claude-opus-4-8` gesendet. Die erste Anfrage schreibt den Cache; die zweite liest ihn.
```json Kalte Anfrage (Cache-Schreibvorgang) theme={null}
{
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 19349,
"cache_read_input_tokens": 0,
"output_tokens": 2,
"total_tokens": 19359,
"sunra_usage_semantics": "anthropic.exclusive.v1"
}
}
```
```json Warme Anfrage (Cache-Lesevorgang) theme={null}
{
"usage": {
"input_tokens": 8,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 19349,
"output_tokens": 2,
"total_tokens": 19359,
"sunra_usage_semantics": "anthropic.exclusive.v1"
}
}
```
`input_tokens` bleibt über beide Anfragen hinweg bei 8, denn 8 ist jedes Mal die tatsächlich neue Eingabe. Das Präfix mit 19.349 Tokens wandert vom Creation-Bucket in den Read-Bucket. Beide Anfragen ergeben in der Summe dieselben 19.359 Gesamt-Tokens, kosten aber nicht dasselbe: Cache-Schreibvorgänge und Cache-Lesevorgänge werden zu jeweils eigenen Token-Preisen abgerechnet, weshalb sie als getrennte Buckets ausgewiesen werden.
## Chat Completions und Responses
Diese Endpoints melden OpenAI-Semantik, unverändert. Die Prompt-Zählung umfasst den **gesamten** Prompt, und gecachte Tokens sind eine **Teilmenge** davon, die separat ausgewiesen wird.
```json /v1/chat/completions theme={null}
{
"usage": {
"prompt_tokens": 19357,
"completion_tokens": 2,
"total_tokens": 19359,
"prompt_tokens_details": {
"cached_tokens": 19349
}
}
}
```
Die Summe aus `prompt_tokens` und `cached_tokens` zählt doppelt. Um die frische Eingabe auf diesen Endpoints zu erhalten, subtrahieren Sie:
```
fresh input = prompt_tokens - prompt_tokens_details.cached_tokens
```
Dieselbe Regel gilt für `/v1/responses` mit `input_tokens` und `input_tokens_details.cached_tokens`.
## Der Marker `sunra_usage_semantics`
Antworten, die Sunra normalisiert hat, tragen innerhalb von `usage` einen Marker:
```json theme={null}
"sunra_usage_semantics": "anthropic.exclusive.v1"
```
Der Marker ist ein Versprechen über die **Antwort**, nicht über ein einzelnes Event oder Feld. Bei einer nicht gestreamten Antwort erscheint er im Wurzelobjekt `usage`; bei einer gestreamten Antwort erscheint er in `message_start`, dem Event, das die Eingabe-Buckets trägt. Wenn er mit diesem Wert vorhanden ist, gelten die Garantien auf dieser Seite: Die drei Eingabe-Buckets schließen sich gegenseitig aus, und `total_tokens` – sofern vorhanden – ist ihre Summe plus `output_tokens`.
**Sein Fehlen ist ebenfalls ein Versprechen.** Sunra normalisiert nur Antwortformen, die es gemessen hat. Alles andere wird unverändert vom Upstream-Provider weitergereicht und bleibt unmarkiert, und eine Antwort ohne den Marker ist eine, für deren Buckets Sunra nicht einsteht.
Prüfen Sie auf den Marker, anstatt die Zahlen zu inspizieren, um zu erraten, welcher Konvention eine Antwort folgt. Genau dieses Erraten anhand der Form soll dieses Feld ersetzen – eine Heuristik wie „die Buckets müssen sich gegenseitig ausschließen, weil sie in der Summe mehr ergeben als die Prompt-Zählung“ wird von mehr als einer Konvention erfüllt und wird irgendwann eine Antwort falsch lesen.
```python theme={null}
usage = response["usage"]
if usage.get("sunra_usage_semantics") == "anthropic.exclusive.v1":
total_prompt = (
usage["input_tokens"]
+ usage.get("cache_creation_input_tokens", 0)
+ usage.get("cache_read_input_tokens", 0)
)
else:
# Not normalized by Sunra. Treat the upstream shape as unverified
# and consult that provider's own documentation.
total_prompt = None
```
Nur Antworten von `/v1/messages` tragen jemals den Marker. Chat Completions und Responses folgen der OpenAI-Spezifikation und werden nicht markiert.
Der Wert ist versioniert. Ein Breaking Change an der Bedeutung dieser Felder wird unter einem neuen Wert ausgeliefert, sodass eine Gleichheitsprüfung gegen `anthropic.exclusive.v1` nicht stillschweigend anfängt, einen anderen Kontrakt zu lesen.
## Streaming
Bei einer gestreamten Messages-Anfrage trifft die Nutzung über zwei Events ein. `message_start` trägt die Eingabeseite und den Marker. Das abschließende `message_delta` trägt nur `output_tokens`. Prüfen Sie auf den Marker in `message_start` und führen Sie die beiden Events dann wie gewohnt zusammen – die Nutzung des späteren Events über die des früheren legen –, um zu den oben dokumentierten Werten zu gelangen.
`total_tokens` wird in gestreamten Antworten weggelassen. Kein einzelnes Event kennt sowohl die Eingabe- als auch die Ausgabeseite, daher wäre jede mitten im Stream berechnete Gesamtsumme falsch. Addieren Sie die Buckets selbst, sobald der Stream abgeschlossen ist.
## Migration vom bisherigen Verhalten
Sunra hat das Upstream-`usage`-Objekt auf `/v1/messages` zuvor unverändert weitergereicht. Die Übersetzungsschicht vor manchen Providern faltet Cache-Creation-Tokens **in** `input_tokens` hinein, sodass ein Aufrufer, der dem Anthropic-Kontrakt folgte und die drei Buckets addierte, die Cache-Creation-Tokens doppelt zählte.
* **Wenn Sie die drei Buckets addieren**, so wie es der Anthropic-Kontrakt beschreibt, liegen Sie jetzt richtig. Auf Ihrer Seite ist keine Änderung erforderlich.
* **Wenn Sie das alte Verhalten kompensiert haben** – indem Sie `cache_creation_input_tokens` selbst von `input_tokens` abgezogen oder die Faltung anderweitig rückentwickelt haben – **hören Sie damit auf**. Diese Korrektur zieht jetzt Tokens ab, die bereits ausgeschlossen waren, und wird Ihre Eingabe zu niedrig ausweisen.
* **Wenn Sie `total_tokens` auslesen**, meldet es weiterhin die vollständige Zählung: frische Eingabe, beide Cache-Buckets und Ausgabe.
Koppeln Sie die Umstellung an den Marker und nicht an ein Deploy-Datum, damit derselbe Codepfad sowohl gegen markierte als auch gegen unmarkierte Antworten korrekt ist.