> ## 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 - Create a cache

> Create a cache from at least one of `contents`, `systemInstruction`, or `tools`, optionally with `toolConfig`, and receive its `name`.

- **Models**: `model` accepts either `models/gemini-3.8-flash` or `gemini-3.8-flash`. Supported models: `gemini-3.8-flash`, `gemini-3.7-flash`, `gemini-3.6-flash`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`, `gemini-3-flash-preview`, `gemini-3.1-flash-lite-preview`, `gemini-3.1-pro-preview`, `gemini-3.1-pro-preview-customtools`, and `gemini-3-pro-preview`. Gemini 4 models do not support explicit caching.
- **Lifetime**: Provide either `ttl`, such as `"3600s"`, or `expireTime` (RFC 3339), but not both. Defaults to 1 hour when neither is provided. Minimum 60 seconds, maximum 168 hours (`604800s`); deleted automatically on expiry.
- **Size**: The request body must not exceed 10 MB. Content must meet the model's minimum cache token count (for example, 4,096 tokens for `gemini-3.8-flash`); otherwise, returns 400.
- **Fields**: Only the documented fields are accepted; other fields return 400.
- **tools**: Only `googleSearch`, `codeExecution`, and `functionDeclarations` are accepted; other tools return 400.
- **Returned `name`**: Has the form `cachedContents/<id>`, where `<id>` is this request's ID. Search for it on the dashboard's Logs page to find the cache creation charge.
- **Billing**: Creation charges a cache write fee (at the input rate) and the storage fee (per million tokens per hour) for the full lifetime upfront. When a cache is referenced, cached tokens are billed at the cache hit rate; if the cache declares `googleSearch`, each search is billed separately. Shortening, deleting, or expiry does not refund storage fees; extensions charge for the added duration. See [Pricing](https://evolink.ai/pricing) for per-model rates.

Authenticate with `Authorization: Bearer`; the `x-goog-api-key` header is also accepted.

> [!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]
>
> **Explicit context caching**: Create a cache from a long prefix you reuse (long documents, system instructions, tool definitions); later generation requests send only the cache name and the new question. Cached tokens are billed at the cache hit rate. A cache write fee and an hourly storage fee also apply; storage is charged upfront for the full lifetime and is not refunded.

> [!TIP]
>
> **Using a cache**: Add `"cachedContent": "<name>"` to the `generateContent` or `streamGenerateContent` request body and put only the new question in `contents`. Requests that reference a cache cannot include `systemInstruction`, `tools`, or `toolConfig`, and must use the same model as the cache.


## OpenAPI

````yaml en/api-manual/language-series/gemini/cached-contents/cached-contents.json POST /v1beta/cachedContents
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:
    post:
      tags:
        - Explicit Context Caching
      summary: Create a cache
      description: >-
        Create a cache from at least one of `contents`, `systemInstruction`, or
        `tools`, optionally with `toolConfig`, and receive its `name`.


        - **Models**: `model` accepts either `models/gemini-3.8-flash` or
        `gemini-3.8-flash`. Supported models: `gemini-3.8-flash`,
        `gemini-3.7-flash`, `gemini-3.6-flash`, `gemini-3.5-flash`,
        `gemini-3.5-flash-lite`, `gemini-3-flash-preview`,
        `gemini-3.1-flash-lite-preview`, `gemini-3.1-pro-preview`,
        `gemini-3.1-pro-preview-customtools`, and `gemini-3-pro-preview`. Gemini
        4 models do not support explicit caching.

        - **Lifetime**: Provide either `ttl`, such as `"3600s"`, or `expireTime`
        (RFC 3339), but not both. Defaults to 1 hour when neither is provided.
        Minimum 60 seconds, maximum 168 hours (`604800s`); deleted automatically
        on expiry.

        - **Size**: The request body must not exceed 10 MB. Content must meet
        the model's minimum cache token count (for example, 4,096 tokens for
        `gemini-3.8-flash`); otherwise, returns 400.

        - **Fields**: Only the documented fields are accepted; other fields
        return 400.

        - **tools**: Only `googleSearch`, `codeExecution`, and
        `functionDeclarations` are accepted; other tools return 400.

        - **Returned `name`**: Has the form `cachedContents/<id>`, where `<id>`
        is this request's ID. Search for it on the dashboard's Logs page to find
        the cache creation charge.

        - **Billing**: Creation charges a cache write fee (at the input rate)
        and the storage fee (per million tokens per hour) for the full lifetime
        upfront. When a cache is referenced, cached tokens are billed at the
        cache hit rate; if the cache declares `googleSearch`, each search is
        billed separately. Shortening, deleting, or expiry does not refund
        storage fees; extensions charge for the added duration. See
        [Pricing](https://evolink.ai/pricing) for per-model rates.


        Authenticate with `Authorization: Bearer`; the `x-goog-api-key` header
        is also accepted.
      operationId: geminiCreateCachedContent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCachedContentRequest'
            examples:
              long_document:
                summary: Cache a long document and system instructions for 1 hour
                value:
                  model: models/gemini-3.8-flash
                  displayName: product-manual-v3
                  systemInstruction:
                    parts:
                      - text: >-
                          You are a product manual assistant. Answer only from
                          the provided manual. If information is absent, say
                          "Not mentioned in the manual".
                  contents:
                    - role: user
                      parts:
                        - text: >-
                            (Insert the full product manual here. Cached content
                            must contain at least 4,096 tokens.)
                  ttl: 3600s
              with_tools:
                summary: >-
                  Cache system instructions and function definitions with an
                  absolute expiry time
                value:
                  model: gemini-3.8-flash
                  displayName: support-agent-tools
                  systemInstruction:
                    parts:
                      - text: >-
                          (Insert lengthy customer support guidelines here,
                          containing at least 4,096 tokens.)
                  contents:
                    - role: user
                      parts:
                        - text: (Examples of past support tickets...)
                  tools:
                    - functionDeclarations:
                        - name: lookup_order
                          description: Look up order status by order number
                          parameters:
                            type: object
                            properties:
                              order_id:
                                type: string
                            required:
                              - order_id
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: >-
            Cache created. `usageMetadata.totalTokenCount` is the cached token
            count used to calculate write and storage fees
          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:20:27.311Z'
                expireTime: '2026-11-03T02:20:26.902Z'
                usageMetadata:
                  totalTokenCount: 7525
        '400':
          description: >-
            Invalid parameters; model does not support explicit caching;
            unavailable for the current user group; content below the minimum
            cache token count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400
                  message: ttl must not exceed 604800s (168h)
                  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 cache write and storage fees
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 402
                  message: insufficient quota for cache storage prepayment
                  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: Explicit caching is not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 404
                  message: explicit context caching is not enabled
                  status: NOT_FOUND
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: EXPLICIT_CACHE_DISABLED
                      domain: evolink.ai
        '413':
          description: Request body exceeds 10 MB
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 413
                  message: >-
                    cache content exceeds 10485760 bytes; reference large files
                    with fileData.fileUri instead
                  status: INVALID_ARGUMENT
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: CACHE_CONTENT_TOO_LARGE
                      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: Service temporarily unavailable; please retry later
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 503
                  message: explicit context caching is temporarily unavailable
                  status: UNAVAILABLE
                  details:
                    - '@type': type.googleapis.com/google.rpc.ErrorInfo
                      reason: INTERNAL
                      domain: evolink.ai
components:
  schemas:
    CreateCachedContentRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: >-
            Model; either `models/gemini-3.8-flash` or `gemini-3.8-flash` is
            accepted. Supported: `gemini-3.8-flash`, `gemini-3.7-flash`,
            `gemini-3.6-flash`, `gemini-3.5-flash`, `gemini-3.5-flash-lite`,
            `gemini-3-flash-preview`, `gemini-3.1-flash-lite-preview`,
            `gemini-3.1-pro-preview`, `gemini-3.1-pro-preview-customtools`,
            `gemini-3-pro-preview`
          example: models/gemini-3.8-flash
        contents:
          type: array
          description: >-
            Conversation content to cache; must be an array. It becomes the
            conversation prefix when referencing the cache. Provide at least one
            of `contents`, `systemInstruction`, or `tools`
          items:
            $ref: '#/components/schemas/Content'
        systemInstruction:
          $ref: '#/components/schemas/Content'
          description: >-
            System instructions. Once cached, systemInstruction must not be
            included in generation requests referencing this cache
        tools:
          type: array
          description: >-
            Tool declarations. Once cached, tools must not be included in
            generation requests referencing this cache
          items:
            $ref: '#/components/schemas/Tool'
        toolConfig:
          type: object
          description: >-
            Tool calling configuration (such as functionCallingConfig). Once
            cached, toolConfig must not be included in generation requests
            referencing this cache
        ttl:
          type: string
          description: >-
            Lifetime, such as `"3600s"`. Minimum `60s`, maximum `604800s` (168
            hours). Mutually exclusive with expireTime; providing both returns
            400. Defaults to `3600s` when neither is provided
          example: 3600s
        expireTime:
          type: string
          format: date-time
          description: >-
            Absolute expiry time (RFC 3339, UTC), mutually exclusive with ttl;
            providing both returns 400
          example: '2026-11-03T06:00:00Z'
        displayName:
          type: string
          maxLength: 255
          description: >-
            A name for your reference, up to 255 characters; does not affect
            billing
          example: product-manual-v3
    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
    Content:
      type: object
      required:
        - parts
      properties:
        role:
          type: string
          enum:
            - user
            - model
          description: Role; not required for system instructions
        parts:
          type: array
          items:
            $ref: '#/components/schemas/Part'
    Tool:
      type: object
      description: >-
        Tool declarations. Only the following three types are accepted; other
        tools are rejected
      properties:
        googleSearch:
          type: object
          description: Web search; provide `{}`
        codeExecution:
          type: object
          description: Code execution; provide `{}`
        functionDeclarations:
          type: array
          description: >-
            Function declarations (parameter structure based on an OpenAPI
            subset)
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              parameters:
                type: object
    Part:
      type: object
      description: 'Content part: choose text, inline data (base64), or a file reference'
      properties:
        text:
          type: string
          description: Text
        inlineData:
          type: object
          description: Inline binary data (images, audio, PDFs, etc.)
          properties:
            mimeType:
              type: string
              example: application/pdf
            data:
              type: string
              description: Base64-encoded data
        fileData:
          type: object
          description: File reference
          properties:
            mimeType:
              type: string
            fileUri:
              type: string
              description: Publicly accessible URL
  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.