プロンプトキャッシング

プロンプトキャッシングにより、プロバイダーは以前に処理したプロンプトコンテンツを再利用できます。プロンプトの先頭が以前にキャッシュされたプレフィックスと一致する場合、プロバイダーはそれらのトークンの再処理をスキップします——コストとレイテンシの両方を大幅に削減します。

キャッシュ使用状況の確認

キャッシュの使用状況はすべてのレスポンスの usage オブジェクトに反映されます：

{
  "usage": {
    "prompt_tokens": 1500,
    "completion_tokens": 100,
    "total_tokens": 1600,
    "prompt_tokens_details": {
      "cached_tokens": 1024,
      "cache_write_tokens": 476
    },
    "completion_tokens_details": {
      "reasoning_tokens": 0
    }
  }
}

フィールド	説明
`prompt_tokens_details.cached_tokens`	キャッシュから読み取られたトークン（キャッシュヒット——安い）
`prompt_tokens_details.cache_write_tokens`	このリクエストでキャッシュに書き込まれたトークン（一回限りの書き込みコスト）

OpenAI 自動キャッシング

OpenAI はプロンプトプレフィックスを自動的にキャッシュします。特別なリクエスト設定は不要です。 仕組み：

キャッシングは OpenAI のサーバー側で、プロンプトが十分長い場合に自動的にトリガーされます
最小プロンプト長：1,024 トークン
キャッシュエントリは約 1 時間の非アクティブ後に期限切れになります
キャッシュされたトークンは割引料金で課金されます（通常 50% 割引）

from openai import OpenAI

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# 繰り返し呼び出すと、長いシステムプロンプトは自動的にキャッシュされる
response = client.chat.completions.create(
    model="openai/gpt-5.4",
    messages=[
        {
            "role": "system",
            "content": "You are an expert assistant. " + "<long context>" * 100,
        },
        {"role": "user", "content": "Summarize the above."},
    ],
)

print(response.usage.prompt_tokens_details)
# PromptTokensDetails(cached_tokens=1024, audio_tokens=0)

Anthropic Claude プロンプトキャッシング

Anthropic は 2 つのキャッシングモードをサポートしています：

自動キャッシング（デフォルト）：Claude がシステムプロンプトを自動的にキャッシュします。最低 1,024 トークン。
明示的キャッシング（cache_control）："cache_control": {"type": "ephemeral"} で特定のコンテンツブロックをマークして、キャッシュする内容を正確に制御します。

キャッシュ TTL

キャッシュタイプ	TTL
自動	5 分
明示的（`ephemeral`）	1 時間（Claude 3.5+）または 5 分（Claude 3）

サポートされるモデル

モデル	最小トークン（テキスト）	最小トークン（画像）
`anthropic/claude-sonnet-4.6`	1,024	1,024
`anthropic/claude-opus-4.5`	1,024	1,024
`anthropic/claude-haiku-3.5`	2,048	2,048
`anthropic/claude-3-5-sonnet`	1,024	1,024

明示的キャッシングの例

cache_control を使用してコンテンツブロックレベルでキャッシングを制御します：

{
  "model": "claude-sonnet-4.6",
  "system": [
    {
      "type": "text",
      "text": "You are a helpful assistant with access to the following reference document:\n\n<document>...</document>",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "messages": [
    { "role": "user", "content": "What does the document say about pricing?" }
  ],
  "max_tokens": 1024
}

OpenAI 互換エンドポイントでは、extra_body を通じて渡します：

Python (OpenAI)
Node.js (OpenAI)
Anthropic SDK

from openai import OpenAI

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

long_document = "<document content here>" * 50  # 1024 トークン以上を確保

response = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": f"Reference document:\n\n{long_document}",
                    "cache_control": {"type": "ephemeral"},
                }
            ],
        },
        {"role": "user", "content": "Summarize the key points."},
    ],
)

print(response.usage)
# Usage(prompt_tokens=1500, completion_tokens=80, total_tokens=1580,
#   prompt_tokens_details=PromptTokensDetails(cached_tokens=1024, cache_write_tokens=476))

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.arouter.ai/v1",
  apiKey: "lr_live_xxxx",
});

const longDocument = "<document content here>".repeat(50);

const response = await client.chat.completions.create({
  model: "anthropic/claude-sonnet-4.6",
  messages: [
    {
      role: "system",
      content: [
        {
          type: "text",
          text: `Reference document:\n\n${longDocument}`,
          // @ts-ignore — cache_control は Anthropic 固有
          cache_control: { type: "ephemeral" },
        },
      ],
    },
    { role: "user", content: "Summarize the key points." },
  ],
});

console.log(response.usage?.prompt_tokens_details);
// { cached_tokens: 1024, cache_write_tokens: 476 }

import anthropic

client = anthropic.Anthropic(
    base_url="https://api.arouter.ai",
    api_key="lr_live_xxxx",
)

long_document = "<document content here>" * 50

response = client.messages.create(
    model="claude-sonnet-4.6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": f"Reference document:\n\n{long_document}",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {"role": "user", "content": "Summarize the key points."}
    ],
)

print(response.usage)
# Usage(input_tokens=1500, output_tokens=80,
#   cache_creation_input_tokens=1024, cache_read_input_tokens=0)

# 2 回目の呼び出し——書き込みではなくキャッシュから読み取り
response2 = client.messages.create(
    model="claude-sonnet-4.6",
    max_tokens=1024,
    system=[
        {
            "type": "text",
            "text": f"Reference document:\n\n{long_document}",
            "cache_control": {"type": "ephemeral"},
        }
    ],
    messages=[
        {"role": "user", "content": "What's the main topic?"}
    ],
)

print(response2.usage)
# Usage(input_tokens=476, output_tokens=40,
#   cache_creation_input_tokens=0, cache_read_input_tokens=1024)

DeepSeek 自動キャッシング

DeepSeek は OpenAI と同様に、プロンプトプレフィックスを自動的にキャッシュします。設定は不要です。

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# DeepSeek は同じプレフィックスで繰り返し呼び出すと自動的にキャッシュ
response = client.chat.completions.create(
    model="deepseek/deepseek-v3.2",
    messages=[
        {"role": "system", "content": "<long context>" * 100},
        {"role": "user", "content": "Analyze the above."},
    ],
)

# usage でキャッシュヒットを確認
print(response.usage.prompt_tokens_details.cached_tokens)

xAI（Grok）自動キャッシング

Grok モデルはリクエスト間で同じプレフィックスを再利用する際に、プロンプトプレフィックスを自動的にキャッシュします。特別な設定は不要です。

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# Grok は同じプレフィックスで繰り返し呼び出すと自動的にキャッシュ
response = client.chat.completions.create(
    model="x-ai/grok-4.20",
    messages=[
        {"role": "system", "content": "<long system prompt>" * 100},
        {"role": "user", "content": "Answer the question."},
    ],
)

# キャッシュヒットは usage に反映される
print(response.usage.prompt_tokens_details)

Groq 自動キャッシング

Groq の推論インフラは対応モデルのプロンプトプレフィックスを自動的にキャッシュします。キャッシュヒットはレイテンシを削減し、レスポンスの usage オブジェクトに反映されます。

client = OpenAI(
    base_url="https://api.arouter.ai/v1",
    api_key="lr_live_xxxx",
)

# Groq は繰り返し呼び出すと自動的にキャッシュ
response = client.chat.completions.create(
    model="groq/meta-llama/llama-4-maverick",
    messages=[
        {"role": "system", "content": "<long context>" * 100},
        {"role": "user", "content": "Analyze the above."},
    ],
)

print(response.usage.prompt_tokens_details.cached_tokens)

Google Gemini プロンプトキャッシング

Gemini は暗黙的（自動）および明示的キャッシングの両方をサポートしています。

暗黙的キャッシング

Gemini 2.5 Flash と Pro は追加コストなしで大きなコンテキストを自動的にキャッシュします。キャッシュヒットはレスポンスの usage に表示されます。

ネイティブ Gemini API による明示的キャッシング

細かい制御のためには、ネイティブの Gemini cachedContents API を使用します。キャッシュオブジェクトを作成し、後続のリクエストで参照します：

{
  "model": "models/gemini-2.5-flash",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "What are the key points in this document?"
        }
      ]
    }
  ],
  "cachedContent": "cachedContents/abc123"
}

ARouter のプロバイダープロキシを経由してネイティブ Gemini エンドポイントを使用してキャッシュされたコンテンツを操作します：

# キャッシュされたコンテンツを作成
curl https://api.arouter.ai/google/v1beta/cachedContents \
  -X POST \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "models/gemini-2.5-flash",
    "contents": [
      {
        "role": "user",
        "parts": [{"text": "<large document content>"}]
      }
    ],
    "ttl": "3600s"
  }'

レスポンスには後続のリクエストで参照する name フィールド（例：cachedContents/abc123）が含まれます：

curl https://api.arouter.ai/google/v1beta/models/gemini-2.5-flash:generateContent \
  -X POST \
  -H "Authorization: Bearer lr_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"role": "user", "parts": [{"text": "Summarize"}]}],
    "cachedContent": "cachedContents/abc123"
  }'

キャッシュ使用状況はレスポンスに表示されます：

{
  "usageMetadata": {
    "promptTokenCount": 200,
    "cachedContentTokenCount": 1500,
    "candidatesTokenCount": 50,
    "totalTokenCount": 250
  }
}

プロバイダースティッキールーティング

キャッシュヒット率を最大化するには、繰り返しのリクエストが同じプロバイダーインスタンスに届く必要があります。ARouter はスティッキールーティングをサポートして、必要なプロバイダーにこれを保証します。リクエストに Anthropic の cache_control ブロックが含まれている場合、ARouter は同じプレフィックスを持つ後続のリクエストを自動的に同じプロバイダーエンドポイントにルーティングし、キャッシュの有効性を維持します。

スティッキールーティングの仕組み

cache_control ブロックを含む最初のリクエストがプロバイダーで処理されキャッシュされます
ARouter はリクエストを処理したプロバイダーインスタンスを記録します
同じキャッシュプレフィックスを持つ後続のリクエストが同じインスタンスにルーティングされます
キャッシュヒットによりコストが下がり（読み取りは書き込みより安い）レイテンシが減少します

キャッシュヒットの確認

usage オブジェクトを確認してリクエスト間のキャッシュヒットを確認します：

# 最初のリクエスト——キャッシュミス、コンテンツが書き込まれる
response1 = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {"role": "system", "content": [{"type": "text", "text": long_doc, "cache_control": {"type": "ephemeral"}}]},
        {"role": "user", "content": "Question 1"},
    ],
)
# prompt_tokens_details.cache_write_tokens > 0
print(response1.usage.prompt_tokens_details)

# 2 回目のリクエスト——キャッシュヒット
response2 = client.chat.completions.create(
    model="anthropic/claude-sonnet-4.6",
    messages=[
        {"role": "system", "content": [{"type": "text", "text": long_doc, "cache_control": {"type": "ephemeral"}}]},
        {"role": "user", "content": "Question 2"},
    ],
)
# prompt_tokens_details.cached_tokens > 0（キャッシュヒット！）
print(response2.usage.prompt_tokens_details)

プロバイダーキャッシュサポートの概要

プロバイダー	キャッシュタイプ	最小トークン	TTL	設定
OpenAI	自動	1,024	約 1 時間	不要
Anthropic	自動 + 明示的	1,024	5 分（自動）、1 時間（明示的）	`cache_control` ブロック
DeepSeek	自動	1,024	プロバイダー定義	不要
Google Gemini	自動 + 明示的	32,768	デフォルト 1 時間	`cachedContents` API
xAI（Grok）	自動	プロバイダー定義	プロバイダー定義	不要
Groq	自動	プロバイダー定義	プロバイダー定義	不要

Documentation Index

​キャッシュ使用状況の確認

​OpenAI 自動キャッシング

​Anthropic Claude プロンプトキャッシング

​キャッシュ TTL

​サポートされるモデル

​明示的キャッシングの例

​DeepSeek 自動キャッシング

​xAI（Grok）自動キャッシング

​Groq 自動キャッシング

​Google Gemini プロンプトキャッシング

​暗黙的キャッシング

​ネイティブ Gemini API による明示的キャッシング

​プロバイダースティッキールーティング

​スティッキールーティングの仕組み

​キャッシュヒットの確認

​プロバイダーキャッシュサポートの概要