# Gemini 显式缓存

Gemini 显式缓存用于复用需要反复发送的大段上下文，例如产品手册、知识库、固定系统规则、图片、音频或视频。先把公共上下文创建为缓存，后续请求只发送 `cache_id` 和本次的新问题，可以减少重复传输与重复处理。

一个缓存会整体保存创建请求中的：

- `systemInstruction`：可选的固定角色和回答规则。
- `contents`：需要复用的文本或媒体资料。

后续的新问题不会自动追加到原缓存。缓存内容创建后不可修改；当前仅支持延长有效期。

本文示例使用 `gemini-2.5-flash`。当前 Gemini 显式缓存仅支持以下模型：

| 模型 ID | 最低缓存 Token 数 |
| --- | ---: |
| `gemini-2.5-flash` | 2,048 |
| `gemini-3.5-flash-lite` | 4,096 |
| `gemini-3.5-flash` | 4,096 |
| `gemini-3.6-flash` | 4,096 |
| `gemini-3.1-pro-preview` | 4,096 |
| `gemini-3-flash-preview` | 4,096 |

创建缓存和使用缓存时必须填写同一个模型。其他 Gemini 模型即使可以正常生成内容，只要未列在上表中，就不能创建显式缓存。

> 显式缓存会产生创建输入费用和存储费用。当前不提供手动删除接口，请根据实际使用时间设置有效期。创建或更新后的最终到期时间不能超过本次请求时间起 7 天。

## 快速开始

### 准备 API Key

本文示例使用以下环境变量：

```bash
export MODELVERSE_API_KEY="<your_api_key>"
export MODELVERSE_BASE_URL="https://api.modelverse.cn"
```

所有接口均使用以下鉴权请求头：

```text
Authorization: Bearer $MODELVERSE_API_KEY
```

缓存按 API Key 隔离。创建、查询、更新和使用同一个缓存时，必须使用创建缓存的 API Key。

### 接口一览

| 操作 | 方法与路径 | 说明 |
| --- | --- | --- |
| 创建缓存 | `POST /v1beta/cachedContents` | 缓存固定规则、文本和媒体，返回 `cache_id`。 |
| 使用缓存 | `POST /v1beta/models/{model}:generateContent` | 引用缓存进行同步生成。 |
| 流式使用缓存 | `POST /v1beta/models/{model}:streamGenerateContent` | 引用缓存进行流式生成。 |
| 查询缓存 | `GET /v1beta/cachedContents` | 查询当前 API Key 下仍有效的缓存。 |
| 延长有效期 | `PATCH /v1beta/cachedContents/{cache_id}` | 只延长有效期，不修改缓存内容。 |

### 第一步：创建缓存

调用 `POST /v1beta/cachedContents`，把固定系统规则和需要复用的资料一起写入缓存：

```bash
curl -X POST "$MODELVERSE_BASE_URL/v1beta/cachedContents" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "displayName": "product-manual",
    "ttl": "3600s",
    "systemInstruction": {
      "parts": [
        {
          "text": "你是产品支持助手。优先依据缓存资料回答；资料中没有答案时明确说明，不要猜测。"
        }
      ]
    },
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "这里放入需要反复使用的完整产品手册、常见问题和处理流程……"
          }
        ]
      }
    ]
  }'
```

示例中的省略内容必须替换为真实的长上下文。`gemini-2.5-flash` 至少需要 2,048 tokens，当前支持的五个 Gemini 3 系列模型至少需要 4,096 tokens。内容过短会创建失败。

创建成功后会返回 ModelVerse 缓存 ID：

```json
{
  "cache_id": "cache_abc123",
  "model": "gemini-2.5-flash",
  "display_name": "product-manual",
  "status": "active",
  "created_at": "2026-07-24T02:00:00Z",
  "updated_at": "2026-07-24T02:00:00Z",
  "expire_time": "2026-07-24T03:00:00Z",
  "total_token_count": 11426
}
```

请保存 `cache_id`。后续接口只使用该 ID，不要传入 Google 的 `projects/.../cachedContents/...` 资源名称。

### 第二步：使用缓存

创建缓存后，调用同一模型的 `generateContent` 接口，只发送 `cachedContent` 和本次的新问题：

```bash
curl -X POST \
  "$MODELVERSE_BASE_URL/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cachedContent": "cache_abc123",
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "请根据缓存的产品手册总结主要功能。"
          }
        ]
      }
    ]
  }'
```

缓存中的 `systemInstruction` 和 `contents` 会一起生效，不需要再次发送。流式接口 `:streamGenerateContent` 也支持相同的 `cachedContent` 写法。

### 第三步：确认缓存命中

缓存命中后，Gemini 响应中的 `usageMetadata` 会包含 `cachedContentTokenCount`：

```json
{
  "usageMetadata": {
    "promptTokenCount": 11436,
    "cachedContentTokenCount": 11426,
    "candidatesTokenCount": 128,
    "totalTokenCount": 11564
  }
}
```

`cachedContentTokenCount` 表示本次请求复用的缓存 token 数。

## 创建缓存

**接口**

```text
POST /v1beta/cachedContents
```

### 请求字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 支持显式缓存的模型 ID：`gemini-2.5-flash`、`gemini-3.5-flash-lite`、`gemini-3.5-flash`、`gemini-3.6-flash`、`gemini-3.1-pro-preview` 或 `gemini-3-flash-preview`。 |
| `contents` | array | 否 | 需要缓存的实际资料，支持 `text` 和 `inlineData` Part。 |
| `systemInstruction` | object | 否 | 需要一起缓存的固定角色和回答规则，仅支持 `text` Part。 |
| `displayName` | string | 否 | 便于识别缓存的展示名称。 |
| `ttl` | string 或 object | 否 | 相对有效期，推荐使用字符串，例如 `"3600s"`。最短为 60 秒，最长为 7 天（604,800 秒）。 |
| `expire_time` | string | 否 | 绝对过期时间，使用 RFC 3339 格式；至少晚于当前时间 60 秒，且不能超过当前时间起 7 天。 |

`contents` 与 `systemInstruction` 至少需要包含一个非空 Part。它们会作为同一个缓存整体保存，不是两个独立缓存。

`ttl` 和 `expire_time` 只能传一个。两者都不传时，Google 默认在创建 60 分钟后过期，具体时间以响应中的 `expire_time` 为准。

无论使用 `ttl` 还是 `expire_time`，创建后的最终到期时间都不能超过本次请求时间起 7 天。

`ttl` 推荐使用字符串：

```json
{
  "ttl": "3600s"
}
```

也支持秒和纳秒对象：

```json
{
  "ttl": {
    "seconds": "3600",
    "nanos": "0"
  }
}
```

使用绝对时间时：

```json
{
  "expire_time": "2026-07-24T10:00:00Z"
}
```

### `systemInstruction` 和 `contents` 的区别

`systemInstruction` 用来定义固定规则，例如角色、回答语言、输出格式和禁止事项；`contents` 用来保存需要反复引用的实际资料。

```json
{
  "systemInstruction": {
    "parts": [
      {
        "text": "只使用中文回答，并严格按照“结论、依据、建议”三个部分输出。"
      }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "这里是需要反复查询的业务资料……"
        }
      ]
    }
  ]
}
```

两部分都会计入缓存 token，也会在引用缓存时一起生效。如果没有固定规则，可以不传 `systemInstruction`。

### 创建响应字段

| 字段 | 说明 |
| --- | --- |
| `cache_id` | ModelVerse 缓存 ID，后续使用、更新时都传这个值。 |
| `model` | 创建缓存时使用的 ModelVerse 模型 ID。 |
| `display_name` | 请求中填写的展示名称；未填写时不返回。 |
| `status` | 缓存状态，创建成功时为 `active`。 |
| `created_at` | 缓存创建时间。 |
| `updated_at` | 最近一次更新时间。 |
| `expire_time` | 上游实际生效的过期时间。 |
| `total_token_count` | 整个缓存的 token 数，包括 `systemInstruction` 和 `contents`。 |

## 使用缓存

**同步接口**

```text
POST /v1beta/models/{model}:generateContent
```

**流式接口**

```text
POST /v1beta/models/{model}:streamGenerateContent
```

使用缓存时需要满足以下条件：

- 使用创建缓存时的同一个 API Key。
- URL 中的模型必须与创建缓存时的 `model` 一致。
- 缓存必须仍处于有效期内。
- `cachedContent` 必须是 ModelVerse 返回的 `cache_id`。
- 请求中不要再次传入 `systemInstruction`、`tools` 或 `toolConfig`。

可以继续传入 `generationConfig`、`safetySettings` 和本次请求独有的 `contents`。

本次请求中的新问题或新媒体不会写回原缓存。如果这些内容也需要在后续请求中反复使用，需要重新创建一个新缓存。

### 使用缓存时增加新图片

本次问题可以同时携带一张未缓存的新图片：

```json
{
  "cachedContent": "cache_abc123",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请将这张最新截图与缓存中的旧截图进行比较。"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<NEW_IMAGE_BASE64>",
            "displayName": "latest-console.png"
          }
        }
      ]
    }
  ]
}
```

## 查询缓存列表

**接口**

```text
GET /v1beta/cachedContents
```

**请求**

```bash
curl "$MODELVERSE_BASE_URL/v1beta/cachedContents" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY"
```

**响应**

```json
{
  "cachedContents": [
    {
      "cache_id": "cache_abc123",
      "model": "gemini-2.5-flash",
      "status": "active",
      "display_name": "product-manual",
      "createTime": "2026-07-24T02:00:00Z",
      "updateTime": "2026-07-24T02:00:00Z",
      "expireTime": "2026-07-24T03:00:00Z",
      "total_token_count": 11426
    }
  ]
}
```

List 接口具有以下行为：

- 只返回当前 API Key 创建的缓存，同一公司下的其他 API Key 也不可见。
- 只返回尚未过期且状态为 `active` 的缓存。
- 每个 `cache_id` 只返回最新的成功状态。
- 按创建时间从新到旧排序。
- 没有有效缓存时返回 `{"cachedContents":[]}`。

> 创建和更新响应的时间字段为 `created_at`、`updated_at`、`expire_time`；List 响应沿用 Gemini 列表结构，时间字段为 `createTime`、`updateTime`、`expireTime`。

## 延长缓存有效期

**接口**

```text
PATCH /v1beta/cachedContents/{cache_id}
```

缓存内容和模型不能修改，更新请求只能延长有效期。请求体必须且只能包含 `ttl` 或 `expire_time` 之一。更新后的最终到期时间不能超过本次请求时间起 7 天。

### 使用相对 TTL 延长

```bash
curl -X PATCH \
  "$MODELVERSE_BASE_URL/v1beta/cachedContents/cache_abc123" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ttl": "600s"
  }'
```

ModelVerse 更新接口中的 `ttl` 表示“在当前过期时间上继续增加多久”。

例如：

- 当前过期时间：`10:30:00Z`
- 请求：`{"ttl":"600s"}`
- 新过期时间：`10:40:00Z`

它不是从发起更新请求的当前时间重新计算。

由于 `ttl` 会累加到当前过期时间，可填写的最大延长时长取决于缓存当前的剩余有效期。例如缓存还剩 1 小时，则本次最多再延长 167 小时，使最终到期时间不超过本次请求时间起 7 天。

### 使用绝对时间延长

```bash
curl -X PATCH \
  "$MODELVERSE_BASE_URL/v1beta/cachedContents/cache_abc123" \
  -H "Authorization: Bearer $MODELVERSE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expire_time": "2026-07-24T12:00:00Z"
  }'
```

新的 `expire_time` 必须晚于当前过期时间、至少晚于请求时间 60 秒，并且不能超过本次请求时间起 7 天。

客户端不需要查询或回传旧过期时间，服务端会读取并校验缓存的当前状态。

### 更新响应

```json
{
  "cache_id": "cache_abc123",
  "model": "gemini-2.5-flash",
  "display_name": "product-manual",
  "status": "active",
  "created_at": "2026-07-24T02:00:00Z",
  "updated_at": "2026-07-24T02:10:00Z",
  "old_expire_time": "2026-07-24T03:00:00Z",
  "expire_time": "2026-07-24T03:10:00Z"
}
```

`old_expire_time` 是更新前的实际过期时间，`expire_time` 是更新后上游实际生效的过期时间。

## 缓存文本和媒体

### Part 组合规则

`contents[].parts[]` 支持：

- `text`：文本。
- `inlineData`：Base64 编码的 Blob。

同一个 `parts` 数组可以同时包含多个文本和 Blob，但每个 Part 必须二选一：

```json
{
  "parts": [
    {
      "text": "这段文本用于说明后面的图片。"
    },
    {
      "inlineData": {
        "mimeType": "image/jpeg",
        "data": "<IMAGE_BASE64>"
      }
    }
  ]
}
```

以下写法无效，因为同一个 Part 同时包含了 `text` 和 `inlineData`：

```json
{
  "text": "错误示例",
  "inlineData": {
    "mimeType": "image/jpeg",
    "data": "<IMAGE_BASE64>"
  }
}
```

`systemInstruction.parts[]` 只支持 `text`，媒体必须放在 `contents[].parts[].inlineData`。

### `inlineData` 字段

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `mimeType` | string | 是 | 文件的标准 MIME 类型，必须与实际内容一致。 |
| `data` | string | 是 | 文件内容的 Base64 字符串，不要添加 Data URL 前缀。 |
| `displayName` | string | 否 | 便于模型和调用方识别文件的名称。 |

所有 `inlineData` 解码后的二进制内容合计不能超过 10 MiB。当前不支持 `fileData`、Cloud Storage URI 或本地文件路径。

### Gemini 常用 MIME 类型

ModelVerse 不为缓存接口额外设置模型无关的 MIME 白名单。缓存能够使用哪些媒体格式，取决于所选 Gemini 模型的多模态输入能力。

下表整理了 Gemini 模型常用的媒体 MIME 类型。本文中的 PNG、JPEG、PDF、MP3 和 MP4 缓存示例已使用 `gemini-2.5-flash` 验证；使用其他格式或切换到上表中的其他支持模型时，以对应模型的 Google 官方说明为准。

| 内容 | 文件格式 | `mimeType` |
| --- | --- | --- |
| 图片 | PNG | `image/png` |
| 图片 | JPEG/JPG | `image/jpeg` |
| 图片 | WebP | `image/webp` |
| 图片 | HEIC | `image/heic` |
| 图片 | HEIF | `image/heif` |
| 文档 | PDF | `application/pdf` |
| 文档 | TXT | `text/plain` |
| 音频 | AAC | `audio/x-aac` |
| 音频 | FLAC | `audio/flac` |
| 音频 | MP3 | `audio/mp3`、`audio/mpeg` |
| 音频 | M4A | `audio/m4a` |
| 音频 | MPGA | `audio/mpga` |
| 音频 | MP4 Audio | `audio/mp4` |
| 音频 | OGG | `audio/ogg` |
| 音频 | PCM | `audio/pcm` |
| 音频 | WAV | `audio/wav` |
| 音频 | WebM Audio | `audio/webm` |
| 视频 | FLV | `video/x-flv` |
| 视频 | MOV/QuickTime | `video/quicktime` |
| 视频 | MPEG | `video/mpeg`、`video/mpegs` |
| 视频 | MPG | `video/mpg` |
| 视频 | MP4 | `video/mp4` |
| 视频 | WebM | `video/webm` |
| 视频 | WMV | `video/wmv` |
| 视频 | 3GPP | `video/3gpp` |

没有列出的 MIME 类型不要直接假定支持。切换模型时，应重新查看对应模型的媒体能力。

参考 Google Vertex 官方文档：

- [Context caching overview](https://cloud.google.com/vertex-ai/generative-ai/docs/context-cache/context-cache-overview)
- [Create a context cache](https://cloud.google.com/vertex-ai/generative-ai/docs/context-cache/context-cache-create)
- [Gemini 2.5 Flash](https://cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/2-5-flash)

### 生成 Base64

macOS：

```bash
base64 -i product-manual.pdf | tr -d '\n'
```

Linux：

```bash
base64 -w 0 product-manual.pdf
```

将输出完整填入 `inlineData.data`。不要添加 `data:application/pdf;base64,` 等 Data URL 前缀。

## 更多创建示例

以下示例只展示发送到 `POST /v1beta/cachedContents` 的 JSON 请求体。

每个示例都需要满足所选模型的最低缓存 token 数；本文使用的 Gemini 2 系列示例至少需要 2,048 tokens。所有 `inlineData` 解码后的二进制内容合计不能超过 10 MiB。`<..._BASE64>` 是占位符，实际调用时必须替换为完整的 Base64 内容。

### 文本和图片

```json
{
  "model": "gemini-2.5-flash",
  "displayName": "product-image-context",
  "ttl": "3600s",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "这是产品控制台截图，蓝色区域表示可用额度，灰色区域表示已使用额度。"
        },
        {
          "inlineData": {
            "mimeType": "image/png",
            "data": "<IMAGE_BASE64>",
            "displayName": "console.png"
          }
        },
        {
          "text": "后续回答需要结合上述界面含义解释截图内容。"
        }
      ]
    }
  ]
}
```

### PDF 和文本说明

```json
{
  "model": "gemini-2.5-flash",
  "displayName": "product-manual",
  "ttl": "7200s",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "application/pdf",
            "data": "<PDF_BASE64>",
            "displayName": "product-manual.pdf"
          }
        },
        {
          "text": "后续问题优先依据这份产品手册回答；手册没有相关信息时明确说明。"
        }
      ]
    }
  ]
}
```

### 文本和多张图片

```json
{
  "model": "gemini-2.5-flash",
  "displayName": "device-images",
  "ttl": "3600s",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "第一张是设备正面："
        },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "<FRONT_IMAGE_BASE64>",
            "displayName": "device-front.jpg"
          }
        },
        {
          "text": "第二张是设备背面："
        },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "<BACK_IMAGE_BASE64>",
            "displayName": "device-back.jpg"
          }
        }
      ]
    }
  ]
}
```

### 音频和背景词表

```json
{
  "model": "gemini-2.5-flash",
  "displayName": "meeting-audio",
  "ttl": "3600s",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "背景词表：ModelVerse 是产品名，UMInfer 是服务名，UCloud 是公司名。"
        },
        {
          "inlineData": {
            "mimeType": "audio/mpeg",
            "data": "<AUDIO_BASE64>",
            "displayName": "weekly-meeting.mp3"
          }
        },
        {
          "text": "后续生成摘要时保留以上专有名词的大小写。"
        }
      ]
    }
  ]
}
```

### 视频和分析要求

```json
{
  "model": "gemini-2.5-flash",
  "displayName": "console-demo-video",
  "ttl": "3600s",
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "inlineData": {
            "mimeType": "video/mp4",
            "data": "<VIDEO_BASE64>",
            "displayName": "console-demo.mp4"
          }
        },
        {
          "text": "这是控制台操作录屏。后续回答需要区分页面跳转、用户输入和系统返回结果。"
        }
      ]
    }
  ]
}
```

### 系统规则、多轮文本和图片

`contents` 可以包含多条 `user`、`model` 消息，用于缓存固定的多模态 Few-shot 示例：

```json
{
  "model": "gemini-2.5-flash",
  "displayName": "inspection-examples",
  "ttl": "3600s",
  "systemInstruction": {
    "parts": [
      {
        "text": "你是设备质检助手，必须按照“外观、接口、风险”三个部分输出。"
      }
    ]
  },
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "请检查这台样例设备。"
        },
        {
          "inlineData": {
            "mimeType": "image/jpeg",
            "data": "<SAMPLE_IMAGE_BASE64>",
            "displayName": "sample-device.jpg"
          }
        }
      ]
    },
    {
      "role": "model",
      "parts": [
        {
          "text": "外观：外壳完整。接口：接口无遮挡。风险：未发现明显风险。"
        }
      ]
    }
  ]
}
```

## 字段命名兼容

接口同时兼容下表中的 camelCase 和 snake_case 写法，本文会根据所在接口的返回结构选用其中一种：

| camelCase | snake_case |
| --- | --- |
| `displayName` | `display_name` |
| `systemInstruction` | `system_instruction` |
| `inlineData` | `inline_data` |
| `mimeType` | `mime_type` |
| `cachedContent` | `cached_content` |
| `expireTime` | `expire_time` |

同一字段不能同时传入 camelCase 和 snake_case 两种写法。

## 生命周期与计费

- 创建缓存时，缓存中的全部 token 会产生一次输入费用。
- 缓存从 `created_at` 保存到 `expire_time`，会产生存储费用。
- 延长缓存只计算原过期时间到新过期时间之间新增的存储费用，不会重复收取创建输入费用。
- 使用缓存生成内容时，缓存 token 按缓存读取计费；本次新增的问题和输出按正常规则计费。
- 使用响应中的 `usageMetadata.cachedContentTokenCount` 可以确认缓存命中量。
- 调用缓存不会自动刷新有效期，需要通过 PATCH 主动延长。
- 创建和每次更新后的最终 `expire_time` 都不能超过对应请求时间起 7 天。
- 当前不提供手动删除接口；缓存到达 `expire_time` 后自动失效，并从 List 结果中消失。

具体价格请以 ModelVerse 计费说明为准。

## 常见错误

| HTTP 状态码 | 常见原因 | 处理建议 |
| --- | --- | --- |
| 400 | JSON 或字段格式错误 | 检查字段名称、Part 结构和 Base64 内容。 |
| 400 | 模型不在显式缓存支持列表中，响应提示 `无节点` | 改用本文“支持模型”表中列出的模型。 |
| 400 | 缓存内容少于模型最低 token 数 | Gemini 2 系列当前至少需要 2,048 tokens，Gemini 3 系列当前至少需要 4,096 tokens。 |
| 400 | 同时传入 `ttl` 和 `expire_time` | 只保留其中一个字段。 |
| 400 | `ttl` 少于 60 秒、新过期时间没有延长，或最终到期时间超过请求时间起 7 天 | 调整有效期，确保新时间晚于当前过期时间且不超过 7 天上限。 |
| 400 | 使用缓存时模型不一致 | 使用创建缓存时相同的模型。 |
| 400 | API Key 没有对应模型权限 | 在控制台为当前 API Key 授予模型权限。 |
| 400 | 传入 `fileData` 或媒体超过 10 MiB | 改用 `inlineData`，并压缩或减少媒体内容；多个 Blob 的解码后总大小仍不能超过 10 MiB。 |
| 401 | API Key 缺失或无效 | 检查 `Authorization: Bearer` 请求头。 |
| 403 | 账号状态或上游权限不允许操作 | 检查账号状态；持续出现时联系技术支持。 |
| 404 | 缓存不存在、已过期或不属于当前 API Key | 检查 `cache_id`、API Key 和 `expire_time`。 |
| 429 | 同一缓存已有更新正在进行，或触发上游限流 | 等待后重试，避免并发更新同一个缓存。 |
| 5xx | 网关或上游服务异常 | 记录响应中的 `trace_id`，稍后重试或联系技术支持。 |

## 常见问题

### 支持哪些模型？

当前支持 `gemini-2.5-flash`、`gemini-3.5-flash-lite`、`gemini-3.5-flash`、`gemini-3.6-flash`、`gemini-3.1-pro-preview` 和 `gemini-3-flash-preview`。普通生成接口支持的其他 Gemini 模型不一定支持显式缓存；创建前请以本文的支持模型表为准。

### 只缓存 `systemInstruction` 吗？

不是。创建请求中的 `systemInstruction` 和 `contents` 会一起组成同一个缓存。`model` 用于绑定模型，`displayName` 和有效期字段属于缓存元数据。

如果只需要缓存一段固定系统规则，也可以只传 `systemInstruction`、省略 `contents`；但系统规则本身仍需满足所选模型的最低缓存 token 数。

### 使用缓存后，新问题会自动写入缓存吗？

不会。每次生成请求中的新 `contents` 只用于本次推理，不会修改原缓存。

### 更新缓存需要传旧过期时间吗？

不需要。只传需要增加的 `ttl`，或新的绝对 `expire_time`。更新后的最终到期时间不能超过本次请求时间起 7 天。响应会返回 `old_expire_time` 和实际生效的新 `expire_time`。

### 同一公司的其他 API Key 可以使用这个缓存吗？

不可以。缓存严格归属于创建它的 API Key。

### 可以使用 Google 返回的完整缓存资源名吗？

不可以。只能使用 ModelVerse 创建响应中的 `cache_id`。

### 可以修改或提前删除缓存内容吗？

当前不支持。缓存内容创建后不可修改，只能延长有效期；到期后自动失效。