> ## 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 Cache explicite du contexte - Prolonger ou réduire la durée

> Seule la durée est modifiable, pas le contenu. Fournissez soit `ttl` (nouvelle durée à partir de **maintenant**, par exemple `"7200s"`), soit `expireTime` (nouvelle date d’expiration absolue).

- L’expiration doit se situer entre 60 secondes et 168 heures à partir de maintenant.
- Seul `ttl` ou `expireTime` est accepté ; fournir les deux ou d’autres champs renvoie 400.
- **Prolongation** : stockage facturé sur la durée ajoutée, en secondes ; toute durée inférieure à 1 seconde est facturée comme 1 seconde. **Réduction** : aucun remboursement du stockage déjà facturé.
- Opération payante : la clé doit avoir accès au modèle ; le tarif de son groupe actuel s’applique. Un solde insuffisant renvoie 402.
- Pour réessayer la même prolongation sans double facturation, utilisez l’en-tête `Idempotency-Key`.

> [!NOTE]
>
> **BaseURL** : La BaseURL par défaut est `https://direct.evolink.ai`, qui offre une meilleure prise en charge des modèles de texte et des connexions persistantes. `https://api.evolink.ai` est le point d'accès principal pour les services multimodaux et sert d'adresse de secours pour les modèles de texte.

> [!NOTE]
>
> Seule la durée peut être modifiée : envoyez `ttl` ou `expireTime`. Une prolongation facture la durée ajoutée ; une réduction n’est pas remboursée.


## OpenAPI

````yaml fr/api-manual/language-series/gemini/cached-contents/cached-contents.json PATCH /v1beta/cachedContents/{id}
openapi: 3.1.0
info:
  title: 'Gemini : mise en cache explicite du contexte (cachedContents)'
  description: >-
    Créez une seule fois un cache pour un long préfixe réutilisable (documents,
    instructions système ou définitions d’outils). Les requêtes de génération
    suivantes n’envoient que le nom du cache et une nouvelle question ; les
    tokens en cache sont facturés au tarif des lectures du cache. Le format suit
    l’interface native cachedContents de Gemini.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: Production (recommandé)
  - url: https://api.evolink.ai
    description: Adresse de secours
security:
  - bearerAuth: []
tags:
  - name: Cache explicite du contexte
    description: Créer, consulter, prolonger et supprimer des caches explicites Gemini
paths:
  /v1beta/cachedContents/{id}:
    patch:
      tags:
        - Cache explicite du contexte
      summary: Prolonger ou réduire la durée
      description: >-
        Seule la durée est modifiable, pas le contenu. Fournissez soit `ttl`
        (nouvelle durée à partir de **maintenant**, par exemple `"7200s"`), soit
        `expireTime` (nouvelle date d’expiration absolue).


        - L’expiration doit se situer entre 60 secondes et 168 heures à partir
        de maintenant.

        - Seul `ttl` ou `expireTime` est accepté ; fournir les deux ou d’autres
        champs renvoie 400.

        - **Prolongation** : stockage facturé sur la durée ajoutée, en secondes
        ; toute durée inférieure à 1 seconde est facturée comme 1 seconde.
        **Réduction** : aucun remboursement du stockage déjà facturé.

        - Opération payante : la clé doit avoir accès au modèle ; le tarif de
        son groupe actuel s’applique. Un solde insuffisant renvoie 402.

        - Pour réessayer la même prolongation sans double facturation, utilisez
        l’en-tête `Idempotency-Key`.
      operationId: geminiUpdateCachedContent
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            Identifiant du cache : le `name` renvoyé à la création, sans le
            préfixe `cachedContents/`. Pour
            `cachedContents/20261103012026348092000s1oTuB96`, utilisez ici
            `20261103012026348092000s1oTuB96`.
          schema:
            type: string
            example: 20261103012026348092000s1oTuB96
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCachedContentRequest'
            examples:
              extend_by_ttl:
                summary: Conserver encore 2 heures à partir de maintenant
                value:
                  ttl: 7200s
              set_expire_time:
                summary: Définir une expiration absolue
                value:
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: Métadonnées mises à jour ; `expireTime` est la nouvelle expiration
          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 absent ou tous deux fournis ; autres champs
            transmis ; expiration hors limites ; cache expiré pendant le
            traitement (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: Clé API absente ou invalide
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '402':
          description: Solde insuffisant pour le stockage supplémentaire
          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 clé n’a pas accès au modèle, l’IP source n’est pas autorisée ou
            le groupe de la clé n’est plus 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: >-
            Cache absent, expiré, supprimé ou appartenant à un autre compte ; ou
            cache explicite non activé
          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: Limite de fréquence dépassée
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '502':
          description: >-
            Service temporairement indisponible. Cette requête n’est pas
            facturée ; réessayez plus tard
          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 temporairement indisponible ; réessayez plus tard
          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: >-
        Fournissez exactement un des champs ttl ou expireTime ; les autres
        champs renvoient 400
      properties:
        ttl:
          type: string
          description: >-
            Nouvelle durée à partir de maintenant, par exemple `"7200s"`.
            Minimum `60s`, maximum `604800s`
          example: 7200s
        expireTime:
          type: string
          format: date-time
          description: Nouvelle expiration absolue (RFC 3339, UTC)
          example: '2026-11-03T06:00:00Z'
    CachedContent:
      type: object
      properties:
        name:
          type: string
          description: >-
            Nom au format `cachedContents/<id>`. À utiliser dans `cachedContent`
            des requêtes de génération ; `<id>` est aussi l’identifiant de la
            requête de création
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: Modèle lié au cache ; la génération doit utiliser le même modèle
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: Nom fourni à la création ; absent si aucun nom n’a été fourni
        createTime:
          type: string
          format: date-time
          description: Date de création (UTC)
        updateTime:
          type: string
          format: date-time
          description: Date de dernière modification (UTC)
        expireTime:
          type: string
          format: date-time
          description: Date d’expiration (UTC) ; suppression automatique à expiration
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: >-
                Total des tokens en cache, utilisé pour les frais d’écriture et
                de stockage
              example: 7525
    ErrorResponse:
      type: object
      description: >-
        Format d’erreur natif Gemini. `error.details[0].reason` contient le code
        : `INVALID_ARGUMENT` paramètres invalides ; `EXPLICIT_CACHE_UNSUPPORTED`
        le modèle ne prend pas en charge le cache explicite ;
        `NO_AVAILABLE_CHANNEL`, `MODEL_PRICE_ERROR` pas encore disponible pour
        votre groupe d’utilisateurs ; `CACHE_EXPIRED` le cache a expiré ou sa
        durée restante est trop courte ; `CACHE_MODEL_MISMATCH` le modèle ne
        correspond pas au cache ; `INVALID_CACHED_CONTENT` `cachedContent` mal
        formé ; `INSUFFICIENT_QUOTA` solde insuffisant ; `CACHE_NOT_FOUND` le
        cache n’existe pas, a expiré, a été supprimé ou appartient à un autre
        compte ; `EXPLICIT_CACHE_DISABLED` la fonctionnalité n’est pas encore
        disponible ; `CACHE_CONTENT_TOO_LARGE` le corps de la requête dépasse 10
        Mo ; `UPSTREAM_ERROR` la requête n’a pas été acceptée, voir `message` ;
        `CACHE_CHANNEL_UNAVAILABLE`, `INTERNAL` temporairement indisponible,
        réessayez plus tard.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: Code de statut HTTP
            message:
              type: string
            status:
              type: string
              description: >-
                Valeur de statut, par exemple 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: >-
        ## Tous les endpoints nécessitent une authentification Bearer Token


        **Obtenir une clé API :**


        Consultez la [gestion des clés API](https://evolink.ai/dashboard/keys).


        **Ajoutez cet en-tête :**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        Le format natif Gemini est aussi accepté : en-tête `x-goog-api-key:
        YOUR_API_KEY` ou paramètre URL `?key=YOUR_API_KEY`.

````

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