> ## 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 Caché explícita de contexto - Crear una caché

> Cree una caché con al menos uno de `contents`, `systemInstruction` o `tools`, y opcionalmente `toolConfig`. Se devuelve su nombre `name`.

- **Modelos**: `model` acepta `models/gemini-3.8-flash` o `gemini-3.8-flash`. Se admiten `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` y `gemini-3-pro-preview`. Gemini 4 no admite caché explícita.
- **Vigencia**: indique `ttl`, como `"3600s"`, o `expireTime` (RFC 3339), nunca ambos. Si omite los dos, se aplica 1 hora. Mínimo 60 segundos, máximo 168 horas (`604800s`); se elimina al caducar.
- **Tamaño**: cuerpo de solicitud de hasta 10 MB. El contenido debe alcanzar el mínimo de tokens del modelo (por ejemplo, 4096 para `gemini-3.8-flash`); de lo contrario, se devuelve 400.
- **Campos**: solo se aceptan los documentados; otros devuelven 400.
- **tools**: solo `googleSearch`, `codeExecution` y `functionDeclarations`; otras herramientas devuelven 400.
- **`name` devuelto**: formato `cachedContents/<id>`; `<id>` es el ID de la solicitud. Búsquelo en «Logs» del panel para ver el cargo de creación.
- **Facturación**: al crear se cobra la escritura en caché (a la tarifa de entrada) y el almacenamiento (por millón de tokens por hora) de toda la vigencia por adelantado. Al usar una caché, los tokens en caché se cobran a la tarifa de acierto de caché; si la caché declara `googleSearch`, cada búsqueda se cobra aparte. Reducir la vigencia, eliminar o caducar no reembolsa el almacenamiento; las ampliaciones cobran el tiempo añadido. Tarifas por modelo: [Precios](https://evolink.ai/pricing).

Autenticación con `Authorization: Bearer`; también se acepta la cabecera `x-goog-api-key`.

> [!NOTE]
>
> **BaseURL**: La BaseURL predeterminada es `https://direct.evolink.ai`, que ofrece mejor compatibilidad con modelos de texto y admite conexiones persistentes. `https://api.evolink.ai` es el endpoint principal para servicios multimodales y actúa como dirección de respaldo para los modelos de texto.

> [!NOTE]
>
> **Caché explícita de contexto**: cree una caché a partir de un prefijo largo que reutiliza (documentos largos, instrucciones del sistema, definiciones de herramientas); las siguientes solicitudes de generación solo envían el nombre de la caché y la nueva pregunta. Los tokens en caché se cobran a la tarifa de acierto de caché. Además se cobra la escritura en caché y un almacenamiento por hora; el almacenamiento se cobra al crear por toda la vigencia y no se reembolsa.

> [!TIP]
>
> **Usar una caché**: añada `"cachedContent": "<name>"` al cuerpo de la solicitud `generateContent` o `streamGenerateContent` y ponga solo la nueva pregunta en `contents`. Las solicitudes que usan una caché no pueden incluir `systemInstruction`, `tools` ni `toolConfig`, y deben usar el mismo modelo que la caché.


## OpenAPI

````yaml es/api-manual/language-series/gemini/cached-contents/cached-contents.json POST /v1beta/cachedContents
openapi: 3.1.0
info:
  title: 'Gemini: caché explícita de contexto (cachedContents)'
  description: >-
    Cree una caché una vez para un prefijo largo reutilizable (documentos,
    instrucciones del sistema o definiciones de herramientas). Las generaciones
    posteriores solo envían el nombre de la caché y una pregunta nueva; los
    tokens en caché se cobran a la tarifa de acierto. El formato coincide con la
    interfaz nativa cachedContents de Gemini.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: Producción (recomendado)
  - url: https://api.evolink.ai
    description: Dirección alternativa
security:
  - bearerAuth: []
tags:
  - name: Caché explícita de contexto
    description: Crear, consultar, ampliar y eliminar cachés explícitas de Gemini
paths:
  /v1beta/cachedContents:
    post:
      tags:
        - Caché explícita de contexto
      summary: Crear una caché
      description: >-
        Cree una caché con al menos uno de `contents`, `systemInstruction` o
        `tools`, y opcionalmente `toolConfig`. Se devuelve su nombre `name`.


        - **Modelos**: `model` acepta `models/gemini-3.8-flash` o
        `gemini-3.8-flash`. Se admiten `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` y
        `gemini-3-pro-preview`. Gemini 4 no admite caché explícita.

        - **Vigencia**: indique `ttl`, como `"3600s"`, o `expireTime` (RFC
        3339), nunca ambos. Si omite los dos, se aplica 1 hora. Mínimo 60
        segundos, máximo 168 horas (`604800s`); se elimina al caducar.

        - **Tamaño**: cuerpo de solicitud de hasta 10 MB. El contenido debe
        alcanzar el mínimo de tokens del modelo (por ejemplo, 4096 para
        `gemini-3.8-flash`); de lo contrario, se devuelve 400.

        - **Campos**: solo se aceptan los documentados; otros devuelven 400.

        - **tools**: solo `googleSearch`, `codeExecution` y
        `functionDeclarations`; otras herramientas devuelven 400.

        - **`name` devuelto**: formato `cachedContents/<id>`; `<id>` es el ID de
        la solicitud. Búsquelo en «Logs» del panel para ver el cargo de
        creación.

        - **Facturación**: al crear se cobra la escritura en caché (a la tarifa
        de entrada) y el almacenamiento (por millón de tokens por hora) de toda
        la vigencia por adelantado. Al usar una caché, los tokens en caché se
        cobran a la tarifa de acierto de caché; si la caché declara
        `googleSearch`, cada búsqueda se cobra aparte. Reducir la vigencia,
        eliminar o caducar no reembolsa el almacenamiento; las ampliaciones
        cobran el tiempo añadido. Tarifas por modelo:
        [Precios](https://evolink.ai/pricing).


        Autenticación con `Authorization: Bearer`; también se acepta la cabecera
        `x-goog-api-key`.
      operationId: geminiCreateCachedContent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCachedContentRequest'
            examples:
              long_document:
                summary: >-
                  Guardar un documento largo e instrucciones del sistema durante
                  1 hora
                value:
                  model: models/gemini-3.8-flash
                  displayName: product-manual-v3
                  systemInstruction:
                    parts:
                      - text: >-
                          Eres un asistente del manual del producto. Responde
                          solo con el manual proporcionado. Si falta
                          información, responde «No se menciona en el manual».
                  contents:
                    - role: user
                      parts:
                        - text: >-
                            (Inserte aquí el manual completo. El contenido en
                            caché debe tener al menos 4096 tokens.)
                  ttl: 3600s
              with_tools:
                summary: >-
                  Guardar instrucciones del sistema y funciones con una
                  caducidad absoluta
                value:
                  model: gemini-3.8-flash
                  displayName: support-agent-tools
                  systemInstruction:
                    parts:
                      - text: >-
                          (Inserte aquí normas extensas de atención al cliente,
                          de al menos 4096 tokens.)
                  contents:
                    - role: user
                      parts:
                        - text: (Ejemplos de incidencias anteriores…)
                  tools:
                    - functionDeclarations:
                        - name: lookup_order
                          description: Consultar el estado de un pedido por su número
                          parameters:
                            type: object
                            properties:
                              order_id:
                                type: string
                            required:
                              - order_id
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: >-
            Caché creada. `usageMetadata.totalTokenCount` es el número de tokens
            usado para calcular escritura y almacenamiento
          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: >-
            Parámetros inválidos; modelo sin caché explícita; no habilitada para
            el grupo actual; contenido inferior al mínimo de tokens
          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 inválida o ausente
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '402':
          description: Saldo insuficiente para escritura y almacenamiento
          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: >-
            La clave no tiene acceso al modelo, la IP de origen no está
            autorizada o el grupo de la clave ya no está disponible
          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: La caché explícita no está habilitada
          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: El cuerpo de la solicitud supera 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: Límite de frecuencia superado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '502':
          description: >-
            Servicio no disponible temporalmente. Esta solicitud no se cobra;
            inténtelo más tarde
          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: Servicio no disponible temporalmente; inténtelo más tarde
          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: >-
            Modelo; se admite `models/gemini-3.8-flash` o `gemini-3.8-flash`.
            Compatibles: `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: >-
            Contenido de conversación que guardar; debe ser un array. Actúa como
            prefijo al usar la caché. Proporcione al menos uno de `contents`,
            `systemInstruction` o `tools`
          items:
            $ref: '#/components/schemas/Content'
        systemInstruction:
          $ref: '#/components/schemas/Content'
          description: >-
            Instrucciones del sistema. Tras guardarlas, no incluya
            systemInstruction en generaciones que usen esta caché
        tools:
          type: array
          description: >-
            Declaraciones de herramientas. Tras guardarlas, no incluya tools en
            generaciones que usen esta caché
          items:
            $ref: '#/components/schemas/Tool'
        toolConfig:
          type: object
          description: >-
            Configuración de llamadas a herramientas (como
            functionCallingConfig). Tras guardarla, no incluya toolConfig en
            generaciones que usen esta caché
        ttl:
          type: string
          description: >-
            Vigencia, como `"3600s"`. Mínimo `60s`, máximo `604800s` (168
            horas). Excluyente con expireTime; ambos devuelven 400. Si omite los
            dos, se usa `3600s`
          example: 3600s
        expireTime:
          type: string
          format: date-time
          description: >-
            Caducidad absoluta (RFC 3339, UTC), excluyente con ttl; ambos
            devuelven 400
          example: '2026-11-03T06:00:00Z'
        displayName:
          type: string
          maxLength: 255
          description: >-
            Nombre para su referencia, hasta 255 caracteres; no afecta a la
            facturación
          example: product-manual-v3
    CachedContent:
      type: object
      properties:
        name:
          type: string
          description: >-
            Nombre con formato `cachedContents/<id>`. Úselo en `cachedContent`
            de las generaciones; `<id>` también es el ID de la solicitud de
            creación
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: Modelo asociado a la caché; la generación debe usar el mismo
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: Nombre indicado al crear; se omite si no se indicó
        createTime:
          type: string
          format: date-time
          description: Fecha de creación (UTC)
        updateTime:
          type: string
          format: date-time
          description: Fecha de última actualización (UTC)
        expireTime:
          type: string
          format: date-time
          description: Caducidad (UTC); se elimina automáticamente al caducar
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: >-
                Total de tokens en caché, usado para calcular escritura y
                almacenamiento
              example: 7525
    ErrorResponse:
      type: object
      description: >-
        Formato de error nativo de Gemini. `error.details[0].reason` contiene el
        código: `INVALID_ARGUMENT` parámetros no válidos;
        `EXPLICIT_CACHE_UNSUPPORTED` el modelo no admite caché explícita;
        `NO_AVAILABLE_CHANNEL`, `MODEL_PRICE_ERROR` aún no disponible para su
        grupo de usuarios; `CACHE_EXPIRED` la caché caducó o le queda muy poca
        vigencia; `CACHE_MODEL_MISMATCH` el modelo no coincide con la caché;
        `INVALID_CACHED_CONTENT` `cachedContent` con formato incorrecto;
        `INSUFFICIENT_QUOTA` saldo insuficiente; `CACHE_NOT_FOUND` la caché no
        existe, caducó, se eliminó o pertenece a otra cuenta;
        `EXPLICIT_CACHE_DISABLED` la función aún no está disponible;
        `CACHE_CONTENT_TOO_LARGE` el cuerpo de la solicitud supera 10 MB;
        `UPSTREAM_ERROR` la solicitud no fue aceptada, consulte `message`;
        `CACHE_CHANNEL_UNAVAILABLE`, `INTERNAL` no disponible temporalmente,
        reintente más tarde.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: Código de estado HTTP
            message:
              type: string
            status:
              type: string
              description: Valor de estado, como 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: Rol; no hace falta en instrucciones del sistema
        parts:
          type: array
          items:
            $ref: '#/components/schemas/Part'
    Tool:
      type: object
      description: >-
        Declaraciones de herramientas. Solo se aceptan los tres tipos
        siguientes; se rechazan los demás
      properties:
        googleSearch:
          type: object
          description: Búsqueda web; indique `{}`
        codeExecution:
          type: object
          description: Ejecución de código; indique `{}`
        functionDeclarations:
          type: array
          description: Declaraciones de funciones (parámetros de un subconjunto de OpenAPI)
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              parameters:
                type: object
    Part:
      type: object
      description: >-
        Parte de contenido: texto, datos integrados (base64) o referencia a
        archivo, a elegir
      properties:
        text:
          type: string
          description: Texto
        inlineData:
          type: object
          description: Datos binarios integrados (imágenes, audio, PDF, etc.)
          properties:
            mimeType:
              type: string
              example: application/pdf
            data:
              type: string
              description: Datos codificados en base64
        fileData:
          type: object
          description: Referencia a archivo
          properties:
            mimeType:
              type: string
            fileUri:
              type: string
              description: URL de acceso público
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ## Todos los endpoints requieren autenticación Bearer Token


        **Obtener una API Key:**


        Visite [Gestión de API Keys](https://evolink.ai/dashboard/keys).


        **Añada esta cabecera:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        También se acepta el formato nativo de Gemini: cabecera `x-goog-api-key:
        YOUR_API_KEY` o parámetro URL `?key=YOUR_API_KEY`.

````

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