Prompt 快取

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	自動	供應商定義	供應商定義	無需設定

快速開始

核心概念

路由

功能特性

使用指南

隱私

管理

最佳實踐

框架與整合

供應商接入

幫助

查看快取使用情況

OpenAI 自動快取

Anthropic Claude Prompt 快取

快取 TTL

支援的模型

顯式快取範例

DeepSeek 自動快取

xAI（Grok）自動快取

Groq 自動快取

Google Gemini Prompt 快取

隱式快取

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

供應商黏性路由

黏性路由運作原理

驗證快取命中

供應商快取支援彙總

​查看快取使用情況

​OpenAI 自動快取

​Anthropic Claude Prompt 快取

​快取 TTL

​支援的模型

​顯式快取範例

​DeepSeek 自動快取

​xAI（Grok）自動快取

​Groq 自動快取

​Google Gemini Prompt 快取

​隱式快取

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

​供應商黏性路由

​黏性路由運作原理

​驗證快取命中

​供應商快取支援彙總

查看快取使用情況

OpenAI 自動快取

Anthropic Claude Prompt 快取

快取 TTL

支援的模型

顯式快取範例

DeepSeek 自動快取

xAI（Grok）自動快取

Groq 自動快取

Google Gemini Prompt 快取

隱式快取

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

供應商黏性路由

黏性路由運作原理

驗證快取命中

供應商快取支援彙總