> ## 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 Explizites Kontext-Caching - Cache erstellen

> Erstellen Sie einen Cache aus mindestens einem der Felder `contents`, `systemInstruction` oder `tools`, optional mit `toolConfig`. Zurückgegeben wird der Cache-Name `name`.

- **Modelle**: `model` akzeptiert `models/gemini-3.8-flash` oder `gemini-3.8-flash`. Unterstützt werden `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` und `gemini-3-pro-preview`. Gemini 4 unterstützt kein explizites Caching.
- **Gültigkeitsdauer**: Entweder `ttl`, z. B. `"3600s"`, oder `expireTime` (RFC 3339), niemals beide. Ohne Angabe gilt 1 Stunde. Minimum 60 Sekunden, Maximum 168 Stunden (`604800s`); nach Ablauf automatische Löschung.
- **Größe**: Maximal 10 MB pro Anfrage. Der Inhalt muss die Mindestanzahl an Cache-Tokens des Modells erreichen (z. B. 4.096 für `gemini-3.8-flash`), andernfalls folgt 400.
- **Felder**: Nur die dokumentierten Felder werden akzeptiert; andere führen zu 400.
- **tools**: Nur `googleSearch`, `codeExecution` und `functionDeclarations` sind zulässig; andere Tools führen zu 400.
- **Zurückgegebener `name`**: Format `cachedContents/<id>`; `<id>` ist die Anfrage-ID. Suchen Sie danach auf der Seite „Logs“ im Dashboard, um die Erstellungsgebühr zu finden.
- **Abrechnung**: Bei Erstellung werden die Cache-Schreibgebühr (zum Eingabepreis) und die Speichergebühr (pro Million Token pro Stunde) für die gesamte Gültigkeitsdauer im Voraus berechnet. Bei Verwendung eines Caches werden gecachte Token zum Cache-Treffer-Preis abgerechnet; deklariert der Cache `googleSearch`, wird jede Suche separat berechnet. Verkürzung, Löschung oder Ablauf führen zu keiner Erstattung der Speichergebühr; Verlängerungen werden für die zusätzliche Dauer berechnet. Preise je Modell: [Preise](https://evolink.ai/pricing).

Authentifizierung über `Authorization: Bearer`; der Header `x-goog-api-key` wird ebenfalls akzeptiert.

> [!NOTE]
>
> **BaseURL**: Die Standard-BaseURL ist `https://direct.evolink.ai` und bietet bessere Unterstützung für Textmodelle sowie persistente Verbindungen. `https://api.evolink.ai` ist der primäre Endpunkt für multimodale Dienste und dient bei Textmodellen als Ausweichadresse.

> [!NOTE]
>
> **Explizites Kontext-Caching**: Erstellen Sie aus einem wiederverwendeten langen Präfix (lange Dokumente, Systemanweisungen, Tool-Definitionen) einen Cache; spätere Generierungsanfragen senden nur den Cache-Namen und die neue Frage. Gecachte Token werden zum Cache-Treffer-Preis abgerechnet. Zusätzlich fallen eine Cache-Schreibgebühr und eine stündliche Speichergebühr an; die Speichergebühr wird bei Erstellung für die gesamte Gültigkeitsdauer berechnet und nicht erstattet.

> [!TIP]
>
> **Cache verwenden**: Fügen Sie dem Request-Body von `generateContent` oder `streamGenerateContent` `"cachedContent": "<name>"` hinzu und geben Sie in `contents` nur die neue Frage an. Anfragen mit Cache dürfen kein `systemInstruction`, `tools` oder `toolConfig` enthalten und müssen dasselbe Modell wie der Cache verwenden.


## OpenAPI

````yaml de/api-manual/language-series/gemini/cached-contents/cached-contents.json POST /v1beta/cachedContents
openapi: 3.1.0
info:
  title: 'Gemini: Explizites Kontext-Caching (cachedContents)'
  description: >-
    Erstellen Sie einmalig einen Cache für ein wiederverwendbares langes Präfix
    (Dokumente, Systemanweisungen oder Tool-Definitionen). Nachfolgende
    Generierungsanfragen senden nur den Cache-Namen und eine neue Frage;
    gecachte Tokens werden zum Cache-Trefferpreis berechnet. Das Format
    entspricht der nativen cachedContents-Schnittstelle von Gemini.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: Produktivumgebung (empfohlen)
  - url: https://api.evolink.ai
    description: Ersatzadresse
security:
  - bearerAuth: []
tags:
  - name: Explizites Kontext-Caching
    description: Explizite Gemini-Caches erstellen, abfragen, verlängern und löschen
paths:
  /v1beta/cachedContents:
    post:
      tags:
        - Explizites Kontext-Caching
      summary: Cache erstellen
      description: >-
        Erstellen Sie einen Cache aus mindestens einem der Felder `contents`,
        `systemInstruction` oder `tools`, optional mit `toolConfig`.
        Zurückgegeben wird der Cache-Name `name`.


        - **Modelle**: `model` akzeptiert `models/gemini-3.8-flash` oder
        `gemini-3.8-flash`. Unterstützt werden `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` und `gemini-3-pro-preview`. Gemini
        4 unterstützt kein explizites Caching.

        - **Gültigkeitsdauer**: Entweder `ttl`, z. B. `"3600s"`, oder
        `expireTime` (RFC 3339), niemals beide. Ohne Angabe gilt 1 Stunde.
        Minimum 60 Sekunden, Maximum 168 Stunden (`604800s`); nach Ablauf
        automatische Löschung.

        - **Größe**: Maximal 10 MB pro Anfrage. Der Inhalt muss die
        Mindestanzahl an Cache-Tokens des Modells erreichen (z. B. 4.096 für
        `gemini-3.8-flash`), andernfalls folgt 400.

        - **Felder**: Nur die dokumentierten Felder werden akzeptiert; andere
        führen zu 400.

        - **tools**: Nur `googleSearch`, `codeExecution` und
        `functionDeclarations` sind zulässig; andere Tools führen zu 400.

        - **Zurückgegebener `name`**: Format `cachedContents/<id>`; `<id>` ist
        die Anfrage-ID. Suchen Sie danach auf der Seite „Logs“ im Dashboard, um
        die Erstellungsgebühr zu finden.

        - **Abrechnung**: Bei Erstellung werden die Cache-Schreibgebühr (zum
        Eingabepreis) und die Speichergebühr (pro Million Token pro Stunde) für
        die gesamte Gültigkeitsdauer im Voraus berechnet. Bei Verwendung eines
        Caches werden gecachte Token zum Cache-Treffer-Preis abgerechnet;
        deklariert der Cache `googleSearch`, wird jede Suche separat berechnet.
        Verkürzung, Löschung oder Ablauf führen zu keiner Erstattung der
        Speichergebühr; Verlängerungen werden für die zusätzliche Dauer
        berechnet. Preise je Modell: [Preise](https://evolink.ai/pricing).


        Authentifizierung über `Authorization: Bearer`; der Header
        `x-goog-api-key` wird ebenfalls akzeptiert.
      operationId: geminiCreateCachedContent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCachedContentRequest'
            examples:
              long_document:
                summary: Langes Dokument und Systemanweisungen für 1 Stunde cachen
                value:
                  model: models/gemini-3.8-flash
                  displayName: product-manual-v3
                  systemInstruction:
                    parts:
                      - text: >-
                          Sie sind ein Assistent für das Produkthandbuch.
                          Antworten Sie nur anhand des bereitgestellten
                          Handbuchs. Fehlt eine Information, antworten Sie „Im
                          Handbuch nicht erwähnt“.
                  contents:
                    - role: user
                      parts:
                        - text: >-
                            (Hier das vollständige Produkthandbuch einfügen. Der
                            Cache-Inhalt muss mindestens 4.096 Tokens
                            enthalten.)
                  ttl: 3600s
              with_tools:
                summary: >-
                  Systemanweisungen und Funktionsdefinitionen mit absolutem
                  Ablaufzeitpunkt cachen
                value:
                  model: gemini-3.8-flash
                  displayName: support-agent-tools
                  systemInstruction:
                    parts:
                      - text: >-
                          (Hier ausführliche Kundendienstrichtlinien mit
                          mindestens 4.096 Tokens einfügen.)
                  contents:
                    - role: user
                      parts:
                        - text: (Beispiele früherer Supportanfragen …)
                  tools:
                    - functionDeclarations:
                        - name: lookup_order
                          description: Bestellstatus anhand der Bestellnummer abfragen
                          parameters:
                            type: object
                            properties:
                              order_id:
                                type: string
                            required:
                              - order_id
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: >-
            Cache erstellt. `usageMetadata.totalTokenCount` ist die Anzahl
            gecachter Tokens für die Berechnung der Schreib- und
            Speichergebühren
          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: >-
            Ungültige Parameter; Modell unterstützt kein explizites Caching; für
            die aktuelle Benutzergruppe nicht freigeschaltet; Mindestanzahl an
            Cache-Tokens unterschritten
          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 ungültig oder fehlt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '402':
          description: Guthaben reicht nicht für Schreib- und Speichergebühren
          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: >-
            Der Key hat keinen Modellzugriff, die Quell-IP steht nicht auf
            seiner Positivliste oder seine Benutzergruppe ist nicht mehr
            verfügbar
          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: Explizites Caching ist nicht freigeschaltet
          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: Anfrageinhalt überschreitet 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: Anfragelimit überschritten
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '502':
          description: >-
            Dienst vorübergehend nicht verfügbar. Diese Anfrage wird nicht
            berechnet; bitte später erneut versuchen
          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: Dienst vorübergehend nicht verfügbar; bitte später erneut versuchen
          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: >-
            Modell; sowohl `models/gemini-3.8-flash` als auch `gemini-3.8-flash`
            sind zulässig. Unterstützt: `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: >-
            Zu cachender Gesprächsinhalt als Array. Er wird beim Verweis auf den
            Cache zum Gesprächspräfix. Mindestens eines von `contents`,
            `systemInstruction` oder `tools` angeben
          items:
            $ref: '#/components/schemas/Content'
        systemInstruction:
          $ref: '#/components/schemas/Content'
          description: >-
            Systemanweisungen. Nach dem Cachen darf systemInstruction nicht
            erneut in Generierungsanfragen mit diesem Cache enthalten sein
        tools:
          type: array
          description: >-
            Tool-Deklarationen. Nach dem Cachen darf tools nicht erneut in
            Generierungsanfragen mit diesem Cache enthalten sein
          items:
            $ref: '#/components/schemas/Tool'
        toolConfig:
          type: object
          description: >-
            Tool-Aufrufkonfiguration (z. B. functionCallingConfig). Nach dem
            Cachen darf toolConfig nicht erneut in Generierungsanfragen mit
            diesem Cache enthalten sein
        ttl:
          type: string
          description: >-
            Gültigkeitsdauer, z. B. `"3600s"`. Minimum `60s`, Maximum `604800s`
            (168 Stunden). Entweder dies oder expireTime; beide führen zu 400.
            Ohne beide gilt `3600s`
          example: 3600s
        expireTime:
          type: string
          format: date-time
          description: >-
            Absoluter Ablaufzeitpunkt (RFC 3339, UTC), alternativ zu ttl; beide
            zusammen führen zu 400
          example: '2026-11-03T06:00:00Z'
        displayName:
          type: string
          maxLength: 255
          description: >-
            Name zur eigenen Orientierung, maximal 255 Zeichen; ohne Einfluss
            auf die Abrechnung
          example: product-manual-v3
    CachedContent:
      type: object
      properties:
        name:
          type: string
          description: >-
            Cache-Name im Format `cachedContents/<id>`. Im Feld `cachedContent`
            der Generierungsanfrage angeben; `<id>` ist zugleich die ID der
            Erstellungsanfrage
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: >-
            An den Cache gebundenes Modell; Generierungsanfragen müssen dasselbe
            Modell verwenden
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: Bei Erstellung vergebener Name; fehlt, wenn keiner angegeben wurde
        createTime:
          type: string
          format: date-time
          description: Erstellungszeit (UTC)
        updateTime:
          type: string
          format: date-time
          description: Zeitpunkt der letzten Änderung (UTC)
        expireTime:
          type: string
          format: date-time
          description: Ablaufzeitpunkt (UTC); danach automatisch gelöscht
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: >-
                Gesamtzahl gecachter Tokens für die Berechnung der Schreib- und
                Speichergebühren
              example: 7525
    ErrorResponse:
      type: object
      description: >-
        Natives Gemini-Fehlerformat. `error.details[0].reason` enthält den
        Grundcode: `INVALID_ARGUMENT` ungültige Parameter;
        `EXPLICIT_CACHE_UNSUPPORTED` das Modell unterstützt kein explizites
        Caching; `NO_AVAILABLE_CHANNEL`, `MODEL_PRICE_ERROR` für Ihre
        Benutzergruppe noch nicht verfügbar; `CACHE_EXPIRED` der Cache ist
        abgelaufen oder die Restlaufzeit ist zu kurz; `CACHE_MODEL_MISMATCH` das
        Modell passt nicht zum Cache; `INVALID_CACHED_CONTENT` ungültiges
        `cachedContent`; `INSUFFICIENT_QUOTA` unzureichendes Guthaben;
        `CACHE_NOT_FOUND` der Cache existiert nicht, ist abgelaufen, gelöscht
        oder gehört zu einem anderen Konto; `EXPLICIT_CACHE_DISABLED` die
        Funktion ist noch nicht verfügbar; `CACHE_CONTENT_TOO_LARGE` der
        Request-Body überschreitet 10 MB; `UPSTREAM_ERROR` die Anfrage wurde
        nicht angenommen, siehe `message`; `CACHE_CHANNEL_UNAVAILABLE`,
        `INTERNAL` vorübergehend nicht verfügbar, später erneut versuchen.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP-Statuscode
            message:
              type: string
            status:
              type: string
              description: Statuswert, z. B. 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: Rolle; für Systemanweisungen nicht erforderlich
        parts:
          type: array
          items:
            $ref: '#/components/schemas/Part'
    Tool:
      type: object
      description: >-
        Tool-Deklarationen. Nur die folgenden drei Typen sind zulässig; andere
        werden abgelehnt
      properties:
        googleSearch:
          type: object
          description: Websuche; `{}` angeben
        codeExecution:
          type: object
          description: Codeausführung; `{}` angeben
        functionDeclarations:
          type: array
          description: Funktionsdeklarationen (Parameterstruktur einer OpenAPI-Teilmenge)
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              parameters:
                type: object
    Part:
      type: object
      description: 'Inhaltsteil: entweder Text, Inline-Daten (base64) oder Dateiverweis'
      properties:
        text:
          type: string
          description: Text
        inlineData:
          type: object
          description: Binäre Inline-Daten (Bilder, Audio, PDF usw.)
          properties:
            mimeType:
              type: string
              example: application/pdf
            data:
              type: string
              description: Base64-kodierte Daten
        fileData:
          type: object
          description: Dateiverweis
          properties:
            mimeType:
              type: string
            fileUri:
              type: string
              description: Öffentlich zugängliche URL
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        ## Alle Endpunkte erfordern Bearer-Token-Authentifizierung


        **API-Key erhalten:**


        Besuchen Sie die
        [API-Key-Verwaltung](https://evolink.ai/dashboard/keys).


        **Diesen Anfrageheader hinzufügen:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        Auch das native Gemini-Format wird akzeptiert: der Header
        `x-goog-api-key: YOUR_API_KEY` oder der URL-Parameter
        `?key=YOUR_API_KEY`.

````

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