> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arouter.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt 快取

> 透過快取重複的提示前綴來降低成本和延遲。支援 OpenAI、Anthropic、DeepSeek 和 Google Gemini。

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

## 查看快取使用情況

快取使用情況反映在每個回應的 `usage` 物件中：

```json theme={null}
{
  "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% 折扣）

```python theme={null}
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` 在內容區塊層級控制快取：

```json theme={null}
{
  "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` 傳遞：

<Tabs>
  <Tab title="Python (OpenAI)">
    ```python theme={null}
    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))
    ```
  </Tab>

  <Tab title="Node.js (OpenAI)">
    ```typescript theme={null}
    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 }
    ```
  </Tab>

  <Tab title="Anthropic SDK">
    ```python theme={null}
    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)
    ```
  </Tab>
</Tabs>

## DeepSeek 自動快取

DeepSeek 與 OpenAI 類似，自動快取提示前綴，無需設定。

```python theme={null}
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 模型在跨請求重用相同前綴時自動快取提示前綴，無需特殊設定。

```python theme={null}
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 物件中。

```python theme={null}
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。您建立快取物件並在後續請求中引用它：

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

透過 ARouter 的供應商代理使用 Gemini 原生端點處理快取內容：

```bash theme={null}
# 建立快取內容
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`），在後續請求中引用：

```bash theme={null}
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"
  }'
```

快取使用情況出現在回應中：

```json theme={null}
{
  "usageMetadata": {
    "promptTokenCount": 200,
    "cachedContentTokenCount": 1500,
    "candidatesTokenCount": 50,
    "totalTokenCount": 250
  }
}
```

## 供應商黏性路由

為最大化快取命中率，您的重複請求應到達**同一供應商實例**。ARouter 支援黏性路由，確保需要的供應商獲得此保證。

當您的請求中包含 Anthropic `cache_control` 區塊時，ARouter 自動將具有相同前綴的後續請求路由到同一供應商端點，保持快取有效性。

### 黏性路由運作原理

1. 帶有 `cache_control` 區塊的首次請求在供應商處處理並快取
2. ARouter 記錄處理該請求的供應商實例
3. 具有相同快取前綴的後續請求被路由到同一實例
4. 快取命中降低您的費用（讀取比寫入便宜）並減少延遲

### 驗證快取命中

檢查 `usage` 物件以確認跨請求的快取命中：

```python theme={null}
# 首次請求——快取未命中，寫入內容
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          | 自動      | 供應商定義    | 供應商定義             | 無需設定                 |