Prompt 快取 - ARouter

Prompt 快取允許供應商重用之前處理過的提示內容。當您的提示開頭與之前快取的前綴匹配時，供應商會跳過重新處理這些 Token——顯著降低成本和延遲。

查看快取使用情況

快取使用情況反映在每個回應的 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`	從快取讀取的 Token（快取命中——更便宜）
`prompt_tokens_details.cache_write_tokens`	本次請求寫入快取的 Token（一次性寫入費用）

OpenAI 自動快取

OpenAI 自動快取提示前綴，無需特殊請求設定。 運作原理：

快取在 OpenAI 伺服器端發生，當提示足夠長時自動觸發
最小提示長度：1,024 Token
快取條目在閒置約 1 小時後過期
快取 Token 按折扣價計費（通常享受 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 Prompt 快取

Anthropic 支援兩種快取模式：

自動快取（預設）：Claude 自動快取系統提示。最少 1,024 Token。
顯式快取（cache_control）：使用 "cache_control": {"type": "ephemeral"} 標記特定內容區塊，精確控制快取內容。

快取 TTL

快取類型	TTL
自動	5 分鐘
顯式（`ephemeral`）	1 小時（Claude 3.5+）或 5 分鐘（Claude 3）

支援的模型

模型	最少 Token（文字）	最少 Token（圖像）
`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 Token

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)

# 第二次呼叫——從快取讀取而非寫入
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 Prompt 快取

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)

# 第二次請求——快取命中
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)

供應商快取支援彙總

供應商	快取類型	最少 Token	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 Prompt 快取

​快取 TTL

​支援的模型

​顯式快取範例

​DeepSeek 自動快取

​xAI（Grok）自動快取

​Groq 自動快取

​Google Gemini Prompt 快取

​隱式快取

​透過 Gemini 原生 API 進行顯式快取

​供應商黏性路由

​黏性路由運作原理

​驗證快取命中

​供應商快取支援彙總