> ## 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 - Créer un cache

> Créez un cache avec au moins un des champs `contents`, `systemInstruction` ou `tools`, et éventuellement `toolConfig`. L’API renvoie son nom `name`.

- **Modèles** : `model` accepte `models/gemini-3.8-flash` ou `gemini-3.8-flash`. Modèles pris en charge : `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` et `gemini-3-pro-preview`. Gemini 4 ne prend pas en charge le cache explicite.
- **Durée** : fournissez soit `ttl`, par exemple `"3600s"`, soit `expireTime` (RFC 3339), jamais les deux. Sans aucun des deux, la durée est de 1 heure. Minimum 60 secondes, maximum 168 heures (`604800s`) ; suppression automatique à expiration.
- **Taille** : corps de requête limité à 10 MB. Le contenu doit atteindre le minimum de tokens requis par le modèle (par exemple 4 096 pour `gemini-3.8-flash`), sinon l’API renvoie 400.
- **Champs** : seuls les champs documentés sont acceptés ; les autres renvoient 400.
- **tools** : seuls `googleSearch`, `codeExecution` et `functionDeclarations` sont acceptés ; les autres outils renvoient 400.
- **`name` renvoyé** : format `cachedContents/<id>` ; `<id>` est l’identifiant de la requête. Recherchez-le dans la page « Logs » du tableau de bord pour retrouver les frais de création.
- **Facturation** : la création facture les frais d’écriture du cache (au tarif d’entrée) et le stockage (par million de tokens et par heure) pour toute la durée, à l’avance. Lors de l’utilisation d’un cache, les tokens en cache sont facturés au tarif de lecture du cache ; si le cache déclare `googleSearch`, chaque recherche est facturée en plus. Réduction de durée, suppression et expiration ne remboursent pas le stockage ; une prolongation facture la durée ajoutée. Tarifs par modèle : [Tarifs](https://evolink.ai/pricing).

Authentification par `Authorization: Bearer` ; l’en-tête `x-goog-api-key` est également accepté.

> [!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]
>
> **Cache explicite du contexte** : créez un cache à partir d’un long préfixe réutilisé (documents longs, instructions système, définitions d’outils) ; les requêtes de génération suivantes n’envoient que le nom du cache et la nouvelle question. Les tokens en cache sont facturés au tarif de lecture du cache. S’y ajoutent des frais d’écriture et un stockage facturé à l’heure ; le stockage est facturé à la création pour toute la durée et n’est pas remboursé.

> [!TIP]
>
> **Utiliser un cache** : ajoutez `"cachedContent": "<name>"` au corps de la requête `generateContent` ou `streamGenerateContent` et ne mettez que la nouvelle question dans `contents`. Les requêtes qui utilisent un cache ne peuvent pas inclure `systemInstruction`, `tools` ni `toolConfig`, et doivent utiliser le même modèle que le cache.


## OpenAPI

````yaml fr/api-manual/language-series/gemini/cached-contents/cached-contents.json POST /v1beta/cachedContents
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:
    post:
      tags:
        - Cache explicite du contexte
      summary: Créer un cache
      description: >-
        Créez un cache avec au moins un des champs `contents`,
        `systemInstruction` ou `tools`, et éventuellement `toolConfig`. L’API
        renvoie son nom `name`.


        - **Modèles** : `model` accepte `models/gemini-3.8-flash` ou
        `gemini-3.8-flash`. Modèles pris en charge : `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` et `gemini-3-pro-preview`. Gemini 4
        ne prend pas en charge le cache explicite.

        - **Durée** : fournissez soit `ttl`, par exemple `"3600s"`, soit
        `expireTime` (RFC 3339), jamais les deux. Sans aucun des deux, la durée
        est de 1 heure. Minimum 60 secondes, maximum 168 heures (`604800s`) ;
        suppression automatique à expiration.

        - **Taille** : corps de requête limité à 10 MB. Le contenu doit
        atteindre le minimum de tokens requis par le modèle (par exemple 4 096
        pour `gemini-3.8-flash`), sinon l’API renvoie 400.

        - **Champs** : seuls les champs documentés sont acceptés ; les autres
        renvoient 400.

        - **tools** : seuls `googleSearch`, `codeExecution` et
        `functionDeclarations` sont acceptés ; les autres outils renvoient 400.

        - **`name` renvoyé** : format `cachedContents/<id>` ; `<id>` est
        l’identifiant de la requête. Recherchez-le dans la page « Logs » du
        tableau de bord pour retrouver les frais de création.

        - **Facturation** : la création facture les frais d’écriture du cache
        (au tarif d’entrée) et le stockage (par million de tokens et par heure)
        pour toute la durée, à l’avance. Lors de l’utilisation d’un cache, les
        tokens en cache sont facturés au tarif de lecture du cache ; si le cache
        déclare `googleSearch`, chaque recherche est facturée en plus. Réduction
        de durée, suppression et expiration ne remboursent pas le stockage ; une
        prolongation facture la durée ajoutée. Tarifs par modèle :
        [Tarifs](https://evolink.ai/pricing).


        Authentification par `Authorization: Bearer` ; l’en-tête
        `x-goog-api-key` est également accepté.
      operationId: geminiCreateCachedContent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCachedContentRequest'
            examples:
              long_document:
                summary: >-
                  Mettre en cache un long document et des instructions système
                  pendant 1 heure
                value:
                  model: models/gemini-3.8-flash
                  displayName: product-manual-v3
                  systemInstruction:
                    parts:
                      - text: >-
                          Vous êtes un assistant de manuel produit. Répondez
                          uniquement à partir du manuel fourni. Si une
                          information manque, répondez « Non mentionné dans le
                          manuel ».
                  contents:
                    - role: user
                      parts:
                        - text: >-
                            (Insérez ici le manuel produit complet. Le contenu
                            mis en cache doit contenir au moins 4 096 tokens.)
                  ttl: 3600s
              with_tools:
                summary: >-
                  Mettre en cache des instructions système et des fonctions avec
                  une expiration absolue
                value:
                  model: gemini-3.8-flash
                  displayName: support-agent-tools
                  systemInstruction:
                    parts:
                      - text: >-
                          (Insérez ici de longues consignes de service client,
                          d’au moins 4 096 tokens.)
                  contents:
                    - role: user
                      parts:
                        - text: (Exemples d’anciens tickets d’assistance…)
                  tools:
                    - functionDeclarations:
                        - name: lookup_order
                          description: Consulter le statut d’une commande par son numéro
                          parameters:
                            type: object
                            properties:
                              order_id:
                                type: string
                            required:
                              - order_id
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: >-
            Cache créé. `usageMetadata.totalTokenCount` est le nombre de tokens
            utilisé pour calculer les frais d’écriture et de stockage
          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: >-
            Paramètres invalides ; modèle sans cache explicite ; fonctionnalité
            non ouverte au groupe actuel ; contenu inférieur au minimum 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: 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 les frais d’écriture et de stockage
          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 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: Le cache explicite n’est pas activé
          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: Le corps de la requête dépasse 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: 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: Service temporairement indisponible ; réessayez plus tard
          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: >-
            Modèle ; `models/gemini-3.8-flash` et `gemini-3.8-flash` sont
            acceptés. Modèles pris en charge : `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: >-
            Contenu de conversation à mettre en cache, obligatoirement un
            tableau. Il devient le préfixe lors de l’utilisation du cache.
            Fournissez au moins un des champs `contents`, `systemInstruction` ou
            `tools`
          items:
            $ref: '#/components/schemas/Content'
        systemInstruction:
          $ref: '#/components/schemas/Content'
          description: >-
            Instructions système. Une fois mises en cache, systemInstruction ne
            doit plus figurer dans les requêtes de génération utilisant ce cache
        tools:
          type: array
          description: >-
            Déclarations d’outils. Une fois mises en cache, tools ne doit plus
            figurer dans les requêtes de génération utilisant ce cache
          items:
            $ref: '#/components/schemas/Tool'
        toolConfig:
          type: object
          description: >-
            Configuration des appels d’outils (par exemple
            functionCallingConfig). Une fois mise en cache, toolConfig ne doit
            plus figurer dans les requêtes de génération utilisant ce cache
        ttl:
          type: string
          description: >-
            Durée, par exemple `"3600s"`. Minimum `60s`, maximum `604800s` (168
            heures). Mutuellement exclusif avec expireTime ; les deux renvoient
            400. Sans les deux, valeur par défaut `3600s`
          example: 3600s
        expireTime:
          type: string
          format: date-time
          description: >-
            Expiration absolue (RFC 3339, UTC), mutuellement exclusive avec ttl
            ; les deux renvoient 400
          example: '2026-11-03T06:00:00Z'
        displayName:
          type: string
          maxLength: 255
          description: >-
            Nom pour votre usage, 255 caractères maximum ; sans effet sur la
            facturation
          example: product-manual-v3
    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
    Content:
      type: object
      required:
        - parts
      properties:
        role:
          type: string
          enum:
            - user
            - model
          description: Rôle ; inutile pour les instructions système
        parts:
          type: array
          items:
            $ref: '#/components/schemas/Part'
    Tool:
      type: object
      description: >-
        Déclarations d’outils. Seuls les trois types suivants sont acceptés ;
        les autres sont rejetés
      properties:
        googleSearch:
          type: object
          description: Recherche web ; fournir `{}`
        codeExecution:
          type: object
          description: Exécution de code ; fournir `{}`
        functionDeclarations:
          type: array
          description: >-
            Déclarations de fonctions (paramètres suivant un sous-ensemble
            d’OpenAPI)
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              parameters:
                type: object
    Part:
      type: object
      description: >-
        Partie de contenu : texte, données intégrées (base64) ou référence de
        fichier, au choix
      properties:
        text:
          type: string
          description: Texte
        inlineData:
          type: object
          description: Données binaires intégrées (images, audio, PDF, etc.)
          properties:
            mimeType:
              type: string
              example: application/pdf
            data:
              type: string
              description: Données encodées en base64
        fileData:
          type: object
          description: Référence de fichier
          properties:
            mimeType:
              type: string
            fileUri:
              type: string
              description: URL accessible publiquement
  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.