Prompt-Caching

Funktionsweise

• Präfix, in dieser Reihenfolge — Der Prompt wird sequenziell gelesen: System-Prompt, Tool-Definitionen und dann die Nachrichten. Der Cache matcht vom Beginn dieser Sequenz bis zum ersten Token, das abweicht.
• Was gilt als Hit — Eine Anfrage, deren Prompt mit demselben Inhalt beginnt wie eine kürzliche Anfrage — typischerweise der vorherige Turn derselben Konversation mit angehängten neuen Nachrichten. Das passende Präfix ist Cached Input; alles danach ist regulärer Input.
• Granularität — Der Cache hält einen Prompt in Blöcken von 1,568 Tokens, daher wird ein Prompt, der kürzer als etwa 1,500 Tokens ist, nicht gecacht. Die Cached-Anzahl in einer Antwort ist Ihre Input-Anzahl multipliziert mit dem gecachten Anteil des Prompts, abgerundet. Sie ist nicht unbedingt ein Vielfaches der Blockgröße.
• Ohne Hit — Eine Anfrage, deren Anfang nicht im Cache liegt, wird zum regulären Input-Preis berechnet. Für gecachte Prompts wird keine Lebensdauer veröffentlicht, und ein Hit ist nicht garantiert: Lesen Sie usage, um zu sehen, was eine Anfrage aus dem Cache bezogen hat.
• Kein Schalter — Eine Anfrage muss nicht zustimmen, und kein Feld schaltet das Caching ab.
• Welche Modelle — Jede hosted open-weight ID. GET /v1/models meldet capabilities.prompt_caching: true sowie pricing.cached_input_per_million_usd für diese. Shannon-Modelle berechnen einen Pauschaltarif.

Einen Cache-Hit in einer Antwort sehen

Senden Sie zwei Anfragen, die mit demselben langen System-Prompt beginnen, und geben Sie die Nutzungsdaten jeder aus. Die erste Zahl ist der Input der Anfrage, die zweite der Teil davon, der aus dem Cache gelesen wurde.

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

handbook = open("handbook.txt").read()  # a long text that stays the same


def ask(question):
    response = client.chat.completions.create(
        model="Kimi-K3-3BIT-REAP",
        messages=[
            {"role": "system", "content": handbook},
            {"role": "user", "content": question},
        ],
    )
    usage = response.usage
    print(usage.prompt_tokens, usage.prompt_tokens_details.cached_tokens)


ask("What is the refund policy?")
ask("Who approves travel?")  # same start: read the second number

import { readFileSync } from "node:fs";
import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });

const handbook = readFileSync("handbook.txt", "utf8"); // a long text that stays the same

async function ask(question) {
  const response = await client.chat.completions.create({
    model: "Kimi-K3-3BIT-REAP",
    messages: [
      { role: "system", content: handbook },
      { role: "user", content: question },
    ],
  });
  const usage = response.usage;
  console.log(usage.prompt_tokens, usage.prompt_tokens_details.cached_tokens);
}

await ask("What is the refund policy?");
await ask("Who approves travel?"); // same start: read the second number

# handbook.txt is a long text that stays the same. jq builds the JSON body from it
# and prints the usage object of the reply. Run it twice with different questions.
jq -Rs '{
    model: "Kimi-K3-3BIT-REAP",
    messages: [
      {role: "system", content: .},
      {role: "user", content: "What is the refund policy?"}
    ]
  }' handbook.txt \
  | curl -s https://api.shannon-ai.com/v1/chat/completions \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d @- \
  | jq .usage

Preise

Cached Input Token werden mit 25 % des Input-Preises des Modells berechnet, gerundet auf $0,001 pro 1M. Das Schreiben in den Cache kostet nichts extra, und der Output wird wie gewohnt berechnet. Der Cached-Tarif jeder ID steht in der Tabelle Models & pricing. Modelle & Preise

Der Input eines Aufrufs wird berechnet als (Input − Cached) × Input-Preis + Cached × Cached-Preis. Die Cached-Anzahl ist nie größer als die Input-Anzahl.

Das Nutzungsprotokoll listet den Cached Input jedes Aufrufs auf. Die abgerechneten Tokens und Kosten enthalten den Cached-Preis bereits. Keys & Nutzung

Usage-Felder

{
  "usage": {
    "prompt_tokens": 20000,
    "completion_tokens": 812,
    "total_tokens": 20812,
    "prompt_tokens_details": {
      "cached_tokens": 18000
    },
    "completion_tokens_details": {
      "reasoning_tokens": 604
    }
  }
}

{
  "usage": {
    "input_tokens": 20000,
    "input_tokens_details": {
      "cached_tokens": 18000
    },
    "output_tokens": 812,
    "output_tokens_details": {
      "reasoning_tokens": 604
    },
    "total_tokens": 20812
  }
}

{
  "usage": {
    "input_tokens": 2000,
    "cache_read_input_tokens": 18000,
    "cache_creation_input_tokens": 0,
    "output_tokens": 812
  }
}

Eine gestreamte Antwort trägt dieselben Felder in ihren abschließenden Nutzungsdaten. Sie müssen sie nicht anfordern:

Mehr Cache-Hits erzielen

• Halten Sie den System-Prompt und die Tool-Definitionen über Calls hinweg byte-identisch. Platzieren Sie variable Werte wie Zeitstempel oder Request-IDs am Ende der letzten Nachricht, nicht im System-Prompt.
• Fügen Sie de Informationen nur an den Verlauf an. Das Editieren, Kürzen oder Zusammenfassen früherer Turns ändert das Präfix, und alles nach der ersten Änderung wird als regulärer Input berechnet.
• Ändern Sie die Reihenfolge von Tools, Nachrichten oder Content-Blöcken zwischen Calls nicht und serialisieren Sie JSON (Tool-Schemas, Argumente und Ergebnisse) jedes Mal auf die gleiche Weise.
• Bleiben Sie für eine Konversation bei einer Modell-ID und senden Sie den Folgeaufruf bald nach dem vorherigen.

Die API hält den Anfang einer Konversation in diesen Fällen stabil:

• Eine system- oder developer-Nachricht, die später in einer Konversation gesendet wird, bleibt an ihrer Stelle. Sie ändert den Anfang des Prompts nicht, sodass die Turns davor gecacht bleiben.
• Die Argumente von Tool-Aufrufen in früheren Assistant-Turns werden nach Wert verglichen. Schlüsselreihenfolge und Abstände dieses JSON spielen keine Rolle.
• Die drei Endpunkte lesen eine Konversation auf dieselbe Weise. Eine Konversation, die an einem anderen Endpunkt fortgesetzt wird, behält ihr gemeinsames Präfix, wenn der Inhalt gleich ist.

Anfragefelder

prompt_cache_key (Chat Completions und Responses) sowie cache_control in Messages-Content-Blöcken werden akzeptiert, sodass bestehender Client-Code unverändert bleibt. Beides ist nicht erforderlich: Caching erfolgt automatisch und funktioniert auch ohne sie identisch.

Token zählen

Zwei kostenlose Endpunkte, POST /v1/tokenize und POST /v1/messages/count_tokens, zählen für die gehosteten Open-Weight-Modelle die Tokens eines Textes oder einer ganzen Anfrage, bevor Sie sie senden. Sie haben eine eigene Seite: Token zählen