> ## 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 - Ampliar o reducir la vigencia

> Solo puede cambiar la vigencia, no el contenido. Indique `ttl` (nueva duración desde **ahora**, como `"7200s"`) o `expireTime` (nueva fecha de caducidad absoluta).

- La nueva caducidad debe estar entre 60 segundos y 168 horas desde ahora.
- Solo se acepta `ttl` o `expireTime`; ambos juntos u otros campos devuelven 400.
- **Ampliar**: se cobra almacenamiento por el tiempo añadido, en segundos; menos de 1 segundo se cobra como 1 segundo. **Reducir**: no se reembolsa el almacenamiento ya cobrado.
- Operación de pago: la clave necesita acceso al modelo y se aplica la tarifa de su grupo actual. Saldo insuficiente devuelve 402.
- Para reintentar la misma ampliación sin cargos duplicados, use `Idempotency-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]
>
> Solo se puede cambiar la vigencia: envíe `ttl` o `expireTime`. Ampliarla cobra el tiempo añadido; reducirla no se reembolsa.


## OpenAPI

````yaml es/api-manual/language-series/gemini/cached-contents/cached-contents.json PATCH /v1beta/cachedContents/{id}
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/{id}:
    patch:
      tags:
        - Caché explícita de contexto
      summary: Ampliar o reducir la vigencia
      description: >-
        Solo puede cambiar la vigencia, no el contenido. Indique `ttl` (nueva
        duración desde **ahora**, como `"7200s"`) o `expireTime` (nueva fecha de
        caducidad absoluta).


        - La nueva caducidad debe estar entre 60 segundos y 168 horas desde
        ahora.

        - Solo se acepta `ttl` o `expireTime`; ambos juntos u otros campos
        devuelven 400.

        - **Ampliar**: se cobra almacenamiento por el tiempo añadido, en
        segundos; menos de 1 segundo se cobra como 1 segundo. **Reducir**: no se
        reembolsa el almacenamiento ya cobrado.

        - Operación de pago: la clave necesita acceso al modelo y se aplica la
        tarifa de su grupo actual. Saldo insuficiente devuelve 402.

        - Para reintentar la misma ampliación sin cargos duplicados, use
        `Idempotency-Key`.
      operationId: geminiUpdateCachedContent
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            ID de caché: el `name` devuelto al crear sin el prefijo
            `cachedContents/`. Para
            `cachedContents/20261103012026348092000s1oTuB96`, use aquí
            `20261103012026348092000s1oTuB96`.
          schema:
            type: string
            example: 20261103012026348092000s1oTuB96
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCachedContentRequest'
            examples:
              extend_by_ttl:
                summary: Conservar otras 2 horas desde ahora
                value:
                  ttl: 7200s
              set_expire_time:
                summary: Establecer una caducidad absoluta
                value:
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: Metadatos actualizados; `expireTime` es la nueva caducidad
          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: >-
            Falta ttl / expireTime o se enviaron ambos; otros campos; caducidad
            fuera de rango; caché caducada durante el procesamiento
            (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 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 el almacenamiento adicional
          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: >-
            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é no existe, ha caducado, se eliminó o pertenece a otra
            cuenta; o la caché explícita no está habilitada
          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: 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: Caché no disponible temporalmente; inténtelo más tarde
          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: Indique exactamente uno de ttl o expireTime; otros campos devuelven 400
      properties:
        ttl:
          type: string
          description: >-
            Nueva duración desde ahora, como `"7200s"`. Mínimo `60s`, máximo
            `604800s`
          example: 7200s
        expireTime:
          type: string
          format: date-time
          description: Nueva caducidad absoluta (RFC 3339, UTC)
          example: '2026-11-03T06:00:00Z'
    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
  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.