> ## 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 - Gültigkeitsdauer verlängern oder verkürzen

> Nur die Gültigkeitsdauer ist änderbar, nicht der Inhalt. Geben Sie entweder `ttl` (neue Dauer ab **jetzt**, z. B. `"7200s"`) oder `expireTime` (neuer absoluter Ablaufzeitpunkt) an.

- Der neue Ablauf muss 60 Sekunden bis 168 Stunden in der Zukunft liegen.
- Nur `ttl` oder `expireTime` wird akzeptiert; beide zusammen oder andere Felder führen zu 400.
- **Verlängern**: Speichergebühr für die zusätzliche Dauer, in Sekunden; weniger als 1 Sekunde wird als 1 Sekunde berechnet. **Verkürzen**: Bereits berechnete Speichergebühren werden nicht erstattet.
- Kostenpflichtiger Vorgang: Der Key benötigt Modellzugriff; es gelten die Preise seiner aktuellen Benutzergruppe. Unzureichendes Guthaben führt zu 402.
- Bei Wiederholung derselben Verlängerungsanfrage verhindert der Header `Idempotency-Key` doppelte Abbuchungen.

> [!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]
>
> Nur die Gültigkeitsdauer kann geändert werden: Senden Sie entweder `ttl` oder `expireTime`. Eine Verlängerung wird für die zusätzliche Dauer berechnet; eine Verkürzung wird nicht erstattet.


## OpenAPI

````yaml de/api-manual/language-series/gemini/cached-contents/cached-contents.json PATCH /v1beta/cachedContents/{id}
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/{id}:
    patch:
      tags:
        - Explizites Kontext-Caching
      summary: Gültigkeitsdauer verlängern oder verkürzen
      description: >-
        Nur die Gültigkeitsdauer ist änderbar, nicht der Inhalt. Geben Sie
        entweder `ttl` (neue Dauer ab **jetzt**, z. B. `"7200s"`) oder
        `expireTime` (neuer absoluter Ablaufzeitpunkt) an.


        - Der neue Ablauf muss 60 Sekunden bis 168 Stunden in der Zukunft
        liegen.

        - Nur `ttl` oder `expireTime` wird akzeptiert; beide zusammen oder
        andere Felder führen zu 400.

        - **Verlängern**: Speichergebühr für die zusätzliche Dauer, in Sekunden;
        weniger als 1 Sekunde wird als 1 Sekunde berechnet. **Verkürzen**:
        Bereits berechnete Speichergebühren werden nicht erstattet.

        - Kostenpflichtiger Vorgang: Der Key benötigt Modellzugriff; es gelten
        die Preise seiner aktuellen Benutzergruppe. Unzureichendes Guthaben
        führt zu 402.

        - Bei Wiederholung derselben Verlängerungsanfrage verhindert der Header
        `Idempotency-Key` doppelte Abbuchungen.
      operationId: geminiUpdateCachedContent
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            Cache-ID: der bei Erstellung zurückgegebene `name` ohne das Präfix
            `cachedContents/`. Bei
            `cachedContents/20261103012026348092000s1oTuB96` hier also
            `20261103012026348092000s1oTuB96` angeben.
          schema:
            type: string
            example: 20261103012026348092000s1oTuB96
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCachedContentRequest'
            examples:
              extend_by_ttl:
                summary: Ab jetzt weitere 2 Stunden behalten
                value:
                  ttl: 7200s
              set_expire_time:
                summary: Absoluten Ablaufzeitpunkt festlegen
                value:
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: >-
            Aktualisierte Cache-Metadaten; `expireTime` ist der neue
            Ablaufzeitpunkt
          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 fehlt oder beide angegeben; andere Felder
            übergeben; Ablauf außerhalb des Bereichs; Cache während der
            Verarbeitung abgelaufen (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 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 die zusätzliche Speichergebühr
          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: >-
            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: >-
            Cache existiert nicht, ist abgelaufen, gelöscht oder gehört einem
            anderen Konto; oder explizites Caching ist nicht freigeschaltet
          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: 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: Cache vorübergehend nicht verfügbar; bitte später erneut versuchen
          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: >-
        Genau eines von ttl oder expireTime ist erforderlich; andere Felder
        führen zu 400
      properties:
        ttl:
          type: string
          description: >-
            Neue Gültigkeitsdauer ab jetzt, z. B. `"7200s"`. Minimum `60s`,
            Maximum `604800s`
          example: 7200s
        expireTime:
          type: string
          format: date-time
          description: Neuer absoluter Ablaufzeitpunkt (RFC 3339, UTC)
          example: '2026-11-03T06:00:00Z'
    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
  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.