Prompt-caching

Hoe het werkt

• Prefix, in volgorde — De prompt wordt in volgorde gelezen: system prompt, tool-definities en vervolgens de berichten. De cache matcht vanaf het begin van die reeks tot aan het eerste token dat afwijkt.
• Wat telt als een hit — Een request waarvan de prompt begint met dezelfde inhoud als een recent request — typisch de vorige beurt van hetzelfde gesprek met nieuwe berichten toegevoegd. De matchende prefix is gecachte input; alles daarna is reguliere input.
• Granulariteit — De cache bewaart een prompt in blokken van 1,568 tokens, dus een prompt korter dan ongeveer 1,500 tokens wordt niet gecachet. Het aantal gecachte tokens in een antwoord is je inputaantal vermenigvuldigd met het gecachte aandeel van de prompt, naar beneden afgerond. Het is niet noodzakelijk een veelvoud van de blokgrootte.
• Zonder hit — Een aanvraag waarvan het begin niet in de cache staat, wordt tegen het gewone inputtarief gefactureerd. Voor gecachte prompts wordt geen levensduur gepubliceerd en een hit is niet gegarandeerd: lees usage om te zien wat een aanvraag uit de cache heeft gehaald.
• Geen schakelaar — Een aanvraag hoeft zich niet aan te melden en geen enkel veld schakelt caching uit.
• Welke modellen — Elke hosted open-weight id. GET /v1/models rapporteert capabilities.prompt_caching: true en pricing.cached_input_per_million_usd voor deze. Shannon-modellen factureren één vast tarief.

Een cache-hit zien in een antwoord

Stuur twee aanvragen die met dezelfde lange systeemprompt beginnen en print de usage van beide. Het eerste getal is de input van de aanvraag, het tweede is het deel daarvan dat uit de cache is gelezen.

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

Prijzen

Gecachte input-tokens worden gefactureerd tegen 25% van het input-tarief van het model, afgerond op $0,001 per 1M. Schrijven naar de cache kost niets extra, en output wordt normaal gefactureerd. Het gecachte tarief per id staat in de Models & pricing tabel. Modellen en prijzen

De input van een call wordt berekend als (input − gecachet) × inputtarief + gecachet × cachetarief. Het aantal gecachte tokens is nooit groter dan het aantal inputtokens.

Het gebruikslog toont de gecachte input van elke call. De gefactureerde tokens en kosten bevatten het cachetarief al. Sleutels en gebruik

Gebruiksvelden

{
  "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
  }
}

Een gestreamd antwoord bevat dezelfde velden in zijn laatste usage. Je hoeft er niet om te vragen:

Meer cache-hits behalen

• Houd de system prompt en tool-definities byte-voor-byte stabiel tussen calls. Plaats waarden per call, zoals timestamps of request-id's, aan het einde van het laatste bericht, niet in de system prompt.
• Voeg alleen toe aan de geschiedenis. Het bewerken, inkorten of samenvatten van eerdere beurten verandert de prefix, waardoor alles na de eerste wijziging als reguliere input wordt gefactureerd.
• Wijzig de volgorde van tools, berichten of content-blokken tussen calls niet, en serialiseer JSON (tool-schema's, tool-argumenten en resultaten) elke keer op dezelfde manier.
• Blijf bij één model-id per gesprek en stuur de vervolgcall kort na de vorige.

De API houdt het begin van een gesprek in deze gevallen stabiel:

• Een system- of developer-bericht dat later in een gesprek wordt verstuurd, blijft op zijn plek. Het verandert het begin van de prompt niet, dus de beurten ervoor blijven gecachet.
• De argumenten van toolcalls in eerdere assistant-beurten worden op waarde vergeleken. De volgorde van de sleutels en de spaties in die JSON maken niet uit.
• De drie endpoints lezen een gesprek op dezelfde manier. Een gesprek dat op een ander endpoint wordt voortgezet, behoudt zijn gedeelde prefix als de inhoud gelijk is.

Request-velden

prompt_cache_key (Chat Completions en Responses) en cache_control op Messages content blocks worden geaccepteerd, zodat bestaande client-code ongewijzigd blijft werken. Geen van beide is verplicht: caching is automatisch en werkt ook zonder deze velden.

Tokens tellen

Twee gratis endpoints, POST /v1/tokenize en POST /v1/messages/count_tokens, tellen voor de gehoste open-weight modellen de tokens van een tekst of van een hele aanvraag voordat je die verstuurt. Ze hebben een eigen pagina: Tokens tellen