Кешування запитів

Як це працює

• Префікс за порядком — Запит зчитується по порядку: системний промпт, визначення інструментів, потім повідомлення. Кеш збігається від початку цієї послідовності до першого токена, що відрізняється.
• Що вважається «потраплянням» (hit) — Запит, промпт якого починається з того самого контенту, що й нещодавній запит — зазвичай це попередній хід тієї самої розмови з додаванням нових повідомлень. Префікс, що збігається, є кешованим входом; все після нього — звичайним входом.
• Гранулярність — Кеш зберігає промпт блоками по 1,568 токенів, тож промпт коротший за приблизно 1,500 токенів не кешується. Кількість кешованих токенів у відповіді — це кількість ваших вхідних токенів, помножена на кешовану частку промпту, із округленням униз. Вона не обов'язково кратна розміру блоку.
• Без потрапляння — Запит, початку якого немає в кеші, тарифікується за звичайним тарифом входу. Строк життя кешованих промптів не публікується, і потрапляння не гарантоване: дивіться usage, щоб побачити, що запит узяв із кешу.
• Без перемикача — Запит не вмикає кешування, і жодне поле його не вимикає.
• Які моделі — Усі хостингові open-weight ID. GET /v1/models повідомляє capabilities.prompt_caching: true та pricing.cached_input_per_million_usd для них. Моделі Shannon мають єдиний фіксований тариф.

Як побачити кеш-потрапляння у відповіді

Надішліть два запити, що починаються з одного довгого системного промпту, і виведіть usage кожного. Перше число — вхід запиту, друге — частина його, прочитана з кешу.

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

Ціноутворення

Кешовані вхідні токени тарифікуються як 25% від вартості входу моделі, округлено до $0.001 за 1M. Запис у кеш не коштує нічого додатково, а вихід тарифікується як зазвичай. Кешований тариф для кожного ID вказано в таблиці Models & pricing. Моделі та ціни

Вхід виклику тарифікується як (вхід − кешований) × тариф входу + кешований × тариф кешу. Кількість кешованих токенів ніколи не перевищує кількість вхідних.

Журнал використання показує кешований вхід кожного виклику. Його тарифіковані токени та вартість уже враховують тариф кешу. Ключі та використання

Поля використання

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

Відповідь у стрімі містить ті самі поля у своєму завершальному usage. Просити про це не потрібно:

Як збільшити кількість кеш-потраплянь

• Зберігайте системний промпт та визначення інструментів байт-в-байт стабільними між викликами. Розміщуйте значення, що змінюються для кожного виклику (наприклад, мітки часу або ID запитів), у кінці останнього повідомлення, а не в системному промпті.
• Тільки додавайте нове до історії. Редагування, обрізання або резюмування попередніх ходів змінює префікс, і все після першої зміни тарифікується як звичайний вхід.
• Не змінюйте порядок інструментів, повідомлень або блоків контенту між викликами та серіалізуйте JSON (схеми інструментів, аргументи та результати) однаково щоразу.
• Лишайтеся на одному id моделі протягом розмови та надсилайте наступний виклик невдовзі після попереднього.

API зберігає початок розмови стабільним у таких випадках:

• Повідомлення system або developer, надіслане пізніше в розмові, залишається на своєму місці. Воно не змінює початок промпту, тож ходи перед ним лишаються кешованими.
• Аргументи викликів інструментів у попередніх ходах асистента порівнюються за значенням. Порядок ключів і пробіли в цьому JSON не мають значення.
• Три ендпоінти читають розмову однаково. Розмова, продовжена на іншому ендпоінті, зберігає спільний префікс, якщо вміст той самий.

Поля запиту

Приймаються prompt_cache_key (для Chat Completions та Responses) та cache_control у блоках контенту Messages, тому існуючий код клієнта працює без змін. Жодне з них не є обов'язковим: кешування автоматичне і працює так само й без них.

Підрахунок токенів

Два безкоштовні ендпоінти, POST /v1/tokenize і POST /v1/messages/count_tokens, підраховують токени тексту або всього запиту для хостованих open-weight моделей до того, як ви його надішлете. Вони мають окрему сторінку: Підрахунок токенів