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

# Gemini 明示的コンテキストキャッシュ - 有効期間を延長・短縮

> 変更できるのは有効期間のみで、内容は変更できません。`ttl`（**現在から**の新しい期間、例：`"7200s"`）または `expireTime`（新しい絶対有効期限）の一方を指定します。

- 新しい有効期限は現在から60秒以上168時間以内です。
- `ttl` または `expireTime` のみ受け付け、両方または他のフィールドを指定すると400です。
- **延長**：追加期間の保存料金を秒単位で徴収し、1秒未満は1秒として計算します。**短縮**：徴収済みの保存料金は返金されません。
- 有料操作です。Key にモデルの利用権限が必要で、現在のユーザーグループの料金が適用されます。残高不足は402です。
- 同じ延長リクエストの再試行時は `Idempotency-Key` ヘッダーで二重課金を防げます。

> [!NOTE]
>
> **BaseURL**：デフォルトの BaseURL は `https://direct.evolink.ai` で、テキストモデルへの対応が優れており、長時間接続をサポートします。`https://api.evolink.ai` はマルチモーダルの主力エンドポイントで、テキストモデルに対しては代替アドレスとして使用されます。

> [!NOTE]
>
> 変更できるのは有効期間のみで、リクエストボディには `ttl` か `expireTime` のどちらかを指定します。延長時は追加期間分の保存料金を徴収し、短縮しても返金されません。


## OpenAPI

````yaml ja/api-manual/language-series/gemini/cached-contents/cached-contents.json PATCH /v1beta/cachedContents/{id}
openapi: 3.1.0
info:
  title: Gemini 明示的コンテキストキャッシュ（cachedContents）
  description: >-
    繰り返し使う長いプレフィックス（文書、システム指示、ツール定義）を一度キャッシュし、以後の生成リクエストではキャッシュ名と新しい質問だけを送ります。キャッシュ部分にはキャッシュヒット単価が適用されます。形式は
    Gemini ネイティブの cachedContents API と同じです。
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: 本番環境（推奨）
  - url: https://api.evolink.ai
    description: 代替アドレス
security:
  - bearerAuth: []
tags:
  - name: 明示的コンテキストキャッシュ
    description: Gemini の明示的キャッシュの作成、取得、延長、削除
paths:
  /v1beta/cachedContents/{id}:
    patch:
      tags:
        - 明示的コンテキストキャッシュ
      summary: 有効期間を延長・短縮
      description: >-
        変更できるのは有効期間のみで、内容は変更できません。`ttl`（**現在から**の新しい期間、例：`"7200s"`）または
        `expireTime`（新しい絶対有効期限）の一方を指定します。


        - 新しい有効期限は現在から60秒以上168時間以内です。

        - `ttl` または `expireTime` のみ受け付け、両方または他のフィールドを指定すると400です。

        - **延長**：追加期間の保存料金を秒単位で徴収し、1秒未満は1秒として計算します。**短縮**：徴収済みの保存料金は返金されません。

        - 有料操作です。Key にモデルの利用権限が必要で、現在のユーザーグループの料金が適用されます。残高不足は402です。

        - 同じ延長リクエストの再試行時は `Idempotency-Key` ヘッダーで二重課金を防げます。
      operationId: geminiUpdateCachedContent
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            キャッシュID：作成時の `name` から `cachedContents/`
            を除いた部分です。`cachedContents/20261103012026348092000s1oTuB96` なら
            `20261103012026348092000s1oTuB96` を指定します。
          schema:
            type: string
            example: 20261103012026348092000s1oTuB96
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCachedContentRequest'
            examples:
              extend_by_ttl:
                summary: 現在からさらに2時間保持
                value:
                  ttl: 7200s
              set_expire_time:
                summary: 絶対有効期限を指定
                value:
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: 更新後のメタデータ。`expireTime` が新しい有効期限です
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CachedContent'
              example:
                name: cachedContents/20261103012026348092000s1oTuB96
                model: models/gemini-3.8-flash
                displayName: product-manual-v3
                createTime: '2026-11-03T01:20:27.311Z'
                updateTime: '2026-11-03T01:35:10.020Z'
                expireTime: '2026-11-03T03:35:10.000Z'
                usageMetadata:
                  totalTokenCount: 7525
        '400':
          description: >-
            ttl / expireTime
            が未指定または両方指定、未対応フィールド、有効期限の範囲外、処理中の期限切れ（CACHE_EXPIRED）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400
                  message: new expiry must be at least 60s in the future
                  status: INVALID_ARGUMENT
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: INVALID_ARGUMENT
                      domain: evolink.ai
        '401':
          description: API Key が無効または未指定
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '402':
          description: 延長分の保存料金に対する残高不足
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 402
                  message: insufficient quota for cache storage extension
                  status: RESOURCE_EXHAUSTED
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: INSUFFICIENT_QUOTA
                      domain: evolink.ai
        '403':
          description: Key にモデル利用権限がない、送信元IPが許可リスト外、または Key のユーザーグループが利用不可
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 403
                  message: This key is not allowed to use model gemini-3.8-flash
                  status: PERMISSION_DENIED
        '404':
          description: キャッシュが存在しない、期限切れ、削除済み、他アカウントに所属、または明示的キャッシュ機能が未提供
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 404
                  message: cached content not found
                  status: NOT_FOUND
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: CACHE_NOT_FOUND
                      domain: evolink.ai
        '429':
          description: レート制限超過
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '502':
          description: サービスが一時的に利用できません。このリクエストは課金されません。後ほど再試行してください
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 502
                  message: >-
                    the request could not be completed due to a service
                    authorization problem; please retry later or contact support
                  status: INTERNAL
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: UPSTREAM_ERROR
                      domain: evolink.ai
        '503':
          description: キャッシュが一時的に利用できません。後ほど再試行してください
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 503
                  message: >-
                    cached content is temporarily unavailable; please retry
                    later
                  status: UNAVAILABLE
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: CACHE_CHANNEL_UNAVAILABLE
                      domain: evolink.ai
components:
  schemas:
    UpdateCachedContentRequest:
      type: object
      description: ttl と expireTime のどちらか一方のみ必須。他のフィールドは400
      properties:
        ttl:
          type: string
          description: 現在からの新しい有効期間（例：`"7200s"`）。最短 `60s`、最長 `604800s`
          example: 7200s
        expireTime:
          type: string
          format: date-time
          description: 新しい絶対有効期限（RFC 3339、UTC）
          example: '2026-11-03T06:00:00Z'
    CachedContent:
      type: object
      properties:
        name:
          type: string
          description: >-
            `cachedContents/<id>` 形式のキャッシュ名。生成リクエストの `cachedContent`
            に指定します。`<id>` は作成リクエストのIDでもあります
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: キャッシュに紐づくモデル。生成時も同じモデルを使用する必要があります
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: 作成時に指定した名前。未指定の場合は返されません
        createTime:
          type: string
          format: date-time
          description: 作成日時（UTC）
        updateTime:
          type: string
          format: date-time
          description: 最終更新日時（UTC）
        expireTime:
          type: string
          format: date-time
          description: 有効期限（UTC）。期限切れ後に自動削除
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: キャッシュの総トークン数。書き込み料金と保存料金の計算に使用
              example: 7525
    ErrorResponse:
      type: object
      description: >-
        Gemini ネイティブのエラー形式。`error.details[0].reason` は理由コードです：`INVALID_ARGUMENT`
        パラメータエラー、`EXPLICIT_CACHE_UNSUPPORTED`
        モデルが明示的キャッシュに非対応、`NO_AVAILABLE_CHANNEL`・`MODEL_PRICE_ERROR`
        現在のユーザーグループでは未提供、`CACHE_EXPIRED`
        キャッシュが期限切れ、または残り有効期間が短すぎる、`CACHE_MODEL_MISMATCH`
        モデルがキャッシュと一致しない、`INVALID_CACHED_CONTENT` `cachedContent`
        の形式が不正、`INSUFFICIENT_QUOTA` 残高不足、`CACHE_NOT_FOUND`
        キャッシュが存在しない・期限切れ・削除済み・他のアカウントのもの、`EXPLICIT_CACHE_DISABLED`
        機能が未提供、`CACHE_CONTENT_TOO_LARGE` リクエストボディが 10 MB を超過、`UPSTREAM_ERROR`
        リクエストが受け付けられなかった（`message` を参照）、`CACHE_CHANNEL_UNAVAILABLE`・`INTERNAL`
        一時的に利用不可、時間をおいて再試行してください。
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP ステータスコード
            message:
              type: string
            status:
              type: string
              description: ステータス値（INVALID_ARGUMENT / NOT_FOUND / UNAVAILABLE など）
            details:
              type: array
              items:
                type: object
                properties:
                  '@type':
                    type: string
                    example: type.googleapis.com/google.rpc.ErrorInfo
                  reason:
                    type: string
                    example: CACHE_NOT_FOUND
                  domain:
                    type: string
                    example: evolink.ai
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ## すべてのエンドポイントは Bearer Token 認証が必要です


        **API Key の取得：**


        [API Key 管理](https://evolink.ai/dashboard/keys)で取得してください。


        **リクエストヘッダーに追加：**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        Gemini ネイティブ形式の `x-goog-api-key: YOUR_API_KEY` ヘッダー、または URL パラメータ
        `?key=YOUR_API_KEY` も使用できます。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.