> ## 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 Explicit Context Caching - Extend or shorten the lifetime

> Only the lifetime can be changed, not the content. Provide either `ttl` (the new lifetime starting **now**, such as `"7200s"`) or `expireTime` (the new absolute expiry time).

- The new expiry must be between 60 seconds and 168 hours from now.
- Only `ttl` or `expireTime` is accepted; providing both or other fields returns 400.
- **Extending**: Storage fees are charged for the added duration, measured in seconds, with durations below 1 second charged as 1 second. **Shortening**: Storage fees already charged are not refunded.
- This is a paid operation: the Key must have access to the model, and the price of its current user group applies. Insufficient balance returns 402.
- When retrying the same extension request, use the `Idempotency-Key` header to avoid duplicate charges.

> [!NOTE]
>
> **BaseURL**: The default BaseURL is `https://direct.evolink.ai`, which has better support for text models and long-lived connections. `https://api.evolink.ai` is the primary endpoint for multimodal services and serves as a fallback address for text models.

> [!NOTE]
>
> Only the lifetime can be changed: send either `ttl` or `expireTime`. Extending charges storage for the added duration; shortening is not refunded.


## OpenAPI

````yaml en/api-manual/language-series/gemini/cached-contents/cached-contents.json PATCH /v1beta/cachedContents/{id}
openapi: 3.1.0
info:
  title: Gemini Explicit Context Caching (cachedContents)
  description: >-
    Create a cache once for a reusable long prefix (documents, system
    instructions, or tool definitions). Subsequent generation requests send only
    the cache name and a new question; cached tokens are billed at the cache hit
    rate. The interface follows the Gemini native cachedContents format.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: Production (recommended)
  - url: https://api.evolink.ai
    description: Fallback endpoint
security:
  - bearerAuth: []
tags:
  - name: Explicit Context Caching
    description: Create, retrieve, extend, and delete Gemini explicit caches
paths:
  /v1beta/cachedContents/{id}:
    patch:
      tags:
        - Explicit Context Caching
      summary: Extend or shorten the lifetime
      description: >-
        Only the lifetime can be changed, not the content. Provide either `ttl`
        (the new lifetime starting **now**, such as `"7200s"`) or `expireTime`
        (the new absolute expiry time).


        - The new expiry must be between 60 seconds and 168 hours from now.

        - Only `ttl` or `expireTime` is accepted; providing both or other fields
        returns 400.

        - **Extending**: Storage fees are charged for the added duration,
        measured in seconds, with durations below 1 second charged as 1 second.
        **Shortening**: Storage fees already charged are not refunded.

        - This is a paid operation: the Key must have access to the model, and
        the price of its current user group applies. Insufficient balance
        returns 402.

        - When retrying the same extension request, use the `Idempotency-Key`
        header to avoid duplicate charges.
      operationId: geminiUpdateCachedContent
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            Cache ID: the `name` returned on creation, without the
            `cachedContents/` prefix. For example, if `name` is
            `cachedContents/20261103012026348092000s1oTuB96`, use
            `20261103012026348092000s1oTuB96` here.
          schema:
            type: string
            example: 20261103012026348092000s1oTuB96
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCachedContentRequest'
            examples:
              extend_by_ttl:
                summary: Keep for another 2 hours from now
                value:
                  ttl: 7200s
              set_expire_time:
                summary: Set an absolute expiry time
                value:
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: Updated cache metadata; `expireTime` is the new expiry time
          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: >-
            Missing ttl / expireTime, or both provided; unsupported fields;
            expiry out of range; cache expired during processing (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 is invalid or missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '402':
          description: Insufficient balance for the additional storage fee
          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: >-
            The Key cannot access this model, the source IP is not on its
            allowlist, or the Key's user group is no longer available
          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: >-
            Cache does not exist, has expired, was deleted, or belongs to
            another account; or explicit caching is not enabled
          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: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '502':
          description: >-
            Service temporarily unavailable. This request is not charged; please
            retry later
          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: Cache temporarily unavailable; please retry later
          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: Provide exactly one of ttl or expireTime; other fields return 400
      properties:
        ttl:
          type: string
          description: >-
            New lifetime starting now, such as `"7200s"`. Minimum `60s`, maximum
            `604800s`
          example: 7200s
        expireTime:
          type: string
          format: date-time
          description: New absolute expiry time (RFC 3339, UTC)
          example: '2026-11-03T06:00:00Z'
    CachedContent:
      type: object
      properties:
        name:
          type: string
          description: >-
            Cache name, in the form `cachedContents/<id>`. Use it in the
            `cachedContent` field of generation requests; `<id>` is also the
            creation request's ID
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: >-
            Model bound to the cache; the generation request must use the same
            model
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: Name provided on creation; omitted if not provided
        createTime:
          type: string
          format: date-time
          description: Creation time (UTC)
        updateTime:
          type: string
          format: date-time
          description: Most recent update time (UTC)
        expireTime:
          type: string
          format: date-time
          description: Expiry time (UTC); automatically deleted on expiry
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: >-
                Total cached token count, used to calculate cache write and
                storage fees
              example: 7525
    ErrorResponse:
      type: object
      description: >-
        Gemini native error format. `error.details[0].reason` is the reason
        code: `INVALID_ARGUMENT` invalid parameters;
        `EXPLICIT_CACHE_UNSUPPORTED` the model does not support explicit
        caching; `NO_AVAILABLE_CHANNEL`, `MODEL_PRICE_ERROR` not yet available
        for your user group; `CACHE_EXPIRED` the cache has expired or has too
        little lifetime left; `CACHE_MODEL_MISMATCH` the model does not match
        the cache; `INVALID_CACHED_CONTENT` malformed `cachedContent`;
        `INSUFFICIENT_QUOTA` insufficient balance; `CACHE_NOT_FOUND` the cache
        does not exist, has expired or been deleted, or belongs to another
        account; `EXPLICIT_CACHE_DISABLED` the feature is not available yet;
        `CACHE_CONTENT_TOO_LARGE` the request body exceeds 10 MB;
        `UPSTREAM_ERROR` the request was not accepted, see `message`;
        `CACHE_CHANNEL_UNAVAILABLE`, `INTERNAL` temporarily unavailable, retry
        later.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP status code
            message:
              type: string
            status:
              type: string
              description: Status enum, such as 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: >-
        ## All endpoints require Bearer Token authentication


        **Get an API Key:**


        Visit [API Key Management](https://evolink.ai/dashboard/keys) to get
        your API Key.


        **Add this request header:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        The Gemini native format is also accepted: the `x-goog-api-key:
        YOUR_API_KEY` header or the `?key=YOUR_API_KEY` URL parameter.

````

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