Skip to main content
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.
/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:
​
integer
Nur frische Eingabe-Tokens. Schließt beide Cache-Buckets aus.
​
integer
Tokens, die von dieser Anfrage in den Cache geschrieben wurden.
​
integer
Tokens, die dieser Anfrage aus dem Cache bereitgestellt wurden.
​
integer
Vom Modell generierte Tokens.
​
integer
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.
Kalte Anfrage (Cache-Schreibvorgang)
Warme Anfrage (Cache-Lesevorgang)
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.
/v1/chat/completions
Die Summe aus prompt_tokens und cached_tokens zählt doppelt. Um die frische Eingabe auf diesen Endpoints zu erhalten, subtrahieren Sie:
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:
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.
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. Eine 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.