> ## 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 명시적 컨텍스트 캐싱 - 유효 기간 연장 또는 단축

> 내용은 바꿀 수 없으며 유효 기간만 변경합니다. `ttl`(**지금부터**의 새 기간, 예: `"7200s"`) 또는 `expireTime`(새 절대 만료 시각) 중 하나를 지정합니다.

- 새 만료 시각은 지금부터 최소 60초, 최대 168시간 후여야 합니다.
- `ttl` 또는 `expireTime`만 허용하며 둘 다 보내거나 다른 필드를 보내면 400입니다.
- **연장**: 추가 기간의 저장 요금을 초 단위로 청구하며 1초 미만은 1초로 계산합니다. **단축**: 이미 청구한 저장 요금은 환불하지 않습니다.
- 유료 작업입니다. Key에 모델 권한이 필요하며 현재 사용자 그룹의 단가를 적용합니다. 잔액 부족은 402입니다.
- 같은 연장 요청을 재시도할 때 `Idempotency-Key` 헤더로 중복 과금을 방지할 수 있습니다.

> [!NOTE]
>
> **BaseURL**: 기본 BaseURL은 `https://direct.evolink.ai`이며, 텍스트 모델 지원이 더 우수하고 장시간 연결을 지원합니다. `https://api.evolink.ai`는 멀티모달 서비스의 주력 엔드포인트이며, 텍스트 모델에 대해서는 대체 주소로 사용됩니다.

> [!NOTE]
>
> 유효 기간만 변경할 수 있으며, 요청 본문에 `ttl` 또는 `expireTime` 중 하나를 보냅니다. 연장 시 추가 기간분 저장 요금을 청구하며, 단축해도 환불되지 않습니다.


## OpenAPI

````yaml ko/api-manual/language-series/gemini/cached-contents/cached-contents.json PATCH /v1beta/cachedContents/{id}
openapi: 3.1.0
info:
  title: Gemini 명시적 컨텍스트 캐싱 (cachedContents)
  description: >-
    반복해서 사용하는 긴 접두사(문서, 시스템 지침, 도구 정의)를 한 번 캐시로 생성합니다. 이후 생성 요청에는 캐시 이름과 새 질문만
    보내며, 캐시 부분에는 캐시 적중 요금이 적용됩니다. 형식은 Gemini 네이티브 cachedContents API와 같습니다.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://direct.evolink.ai
    description: 프로덕션 (권장)
  - url: https://api.evolink.ai
    description: 대체 주소
security:
  - bearerAuth: []
tags:
  - name: 명시적 컨텍스트 캐싱
    description: Gemini 명시적 캐시 생성, 조회, 연장 및 삭제
paths:
  /v1beta/cachedContents/{id}:
    patch:
      tags:
        - 명시적 컨텍스트 캐싱
      summary: 유효 기간 연장 또는 단축
      description: >-
        내용은 바꿀 수 없으며 유효 기간만 변경합니다. `ttl`(**지금부터**의 새 기간, 예: `"7200s"`) 또는
        `expireTime`(새 절대 만료 시각) 중 하나를 지정합니다.


        - 새 만료 시각은 지금부터 최소 60초, 최대 168시간 후여야 합니다.

        - `ttl` 또는 `expireTime`만 허용하며 둘 다 보내거나 다른 필드를 보내면 400입니다.

        - **연장**: 추가 기간의 저장 요금을 초 단위로 청구하며 1초 미만은 1초로 계산합니다. **단축**: 이미 청구한 저장
        요금은 환불하지 않습니다.

        - 유료 작업입니다. Key에 모델 권한이 필요하며 현재 사용자 그룹의 단가를 적용합니다. 잔액 부족은 402입니다.

        - 같은 연장 요청을 재시도할 때 `Idempotency-Key` 헤더로 중복 과금을 방지할 수 있습니다.
      operationId: geminiUpdateCachedContent
      parameters:
        - name: id
          in: path
          required: true
          description: >-
            캐시 ID: 생성 시 반환된 `name`에서 `cachedContents/`를 뺀 부분입니다.
            `cachedContents/20261103012026348092000s1oTuB96`이면
            `20261103012026348092000s1oTuB96`을 지정합니다.
          schema:
            type: string
            example: 20261103012026348092000s1oTuB96
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateCachedContentRequest'
            examples:
              extend_by_ttl:
                summary: 지금부터 2시간 더 보관
                value:
                  ttl: 7200s
              set_expire_time:
                summary: 절대 만료 시각 지정
                value:
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: 갱신된 캐시 메타데이터. `expireTime`은 새 만료 시각입니다
          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 누락 또는 동시 지정, 다른 필드 전송, 만료 시각 범위 초과, 처리 중
            만료(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가 없거나 유효하지 않음
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401
                  message: Invalid API key
                  status: UNAUTHENTICATED
        '402':
          description: 추가 저장 요금을 지불할 잔액 부족
          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: Key에 모델 권한이 없거나 출발지 IP가 허용 목록에 없거나 Key의 사용자 그룹을 더 이상 사용할 수 없음
          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: 캐시가 없거나 만료·삭제되었거나 다른 계정 소유임, 또는 명시적 캐시 기능이 활성화되지 않음
          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: 요청 빈도 제한 초과
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 429
                  message: Rate limit exceeded
                  status: RESOURCE_EXHAUSTED
        '502':
          description: 서비스를 일시적으로 사용할 수 없습니다. 이 요청은 과금되지 않으며 나중에 다시 시도하세요
          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: 캐시를 일시적으로 사용할 수 없습니다. 나중에 다시 시도하세요
          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: ttl 또는 expireTime 중 정확히 하나 필수. 다른 필드는 400
      properties:
        ttl:
          type: string
          description: '지금부터의 새 유효 기간(예: `"7200s"`). 최소 `60s`, 최대 `604800s`'
          example: 7200s
        expireTime:
          type: string
          format: date-time
          description: 새 절대 만료 시각(RFC 3339, UTC)
          example: '2026-11-03T06:00:00Z'
    CachedContent:
      type: object
      properties:
        name:
          type: string
          description: >-
            `cachedContents/<id>` 형식의 이름. 생성 요청의 `cachedContent`에 지정하며 `<id>`는
            생성 요청 ID이기도 합니다
          example: cachedContents/20261103012026348092000s1oTuB96
        model:
          type: string
          description: 캐시에 연결된 모델. 생성 요청도 같은 모델을 사용해야 함
          example: models/gemini-3.8-flash
        displayName:
          type: string
          description: 생성 시 지정한 이름. 지정하지 않았다면 반환하지 않음
        createTime:
          type: string
          format: date-time
          description: 생성 시각(UTC)
        updateTime:
          type: string
          format: date-time
          description: 마지막 수정 시각(UTC)
        expireTime:
          type: string
          format: date-time
          description: 만료 시각(UTC). 만료 후 자동 삭제
        usageMetadata:
          type: object
          properties:
            totalTokenCount:
              type: integer
              description: 캐시의 총 토큰 수. 쓰기 및 저장 요금 계산에 사용
              example: 7525
    ErrorResponse:
      type: object
      description: >-
        Gemini 네이티브 오류 형식. `error.details[0].reason`은 사유 코드입니다:
        `INVALID_ARGUMENT` 매개변수 오류, `EXPLICIT_CACHE_UNSUPPORTED` 모델이 명시적 캐싱 미지원,
        `NO_AVAILABLE_CHANNEL`·`MODEL_PRICE_ERROR` 현재 사용자 그룹에서 아직 미제공,
        `CACHE_EXPIRED` 캐시가 만료되었거나 남은 유효 기간이 너무 짧음, `CACHE_MODEL_MISMATCH` 모델이
        캐시와 불일치, `INVALID_CACHED_CONTENT` `cachedContent` 형식 오류,
        `INSUFFICIENT_QUOTA` 잔액 부족, `CACHE_NOT_FOUND` 캐시가 없거나 만료·삭제되었거나 다른 계정
        소유, `EXPLICIT_CACHE_DISABLED` 기능 미제공, `CACHE_CONTENT_TOO_LARGE` 요청 본문이
        10MB 초과, `UPSTREAM_ERROR` 요청이 수락되지 않음(`message` 참고),
        `CACHE_CHANNEL_UNAVAILABLE`·`INTERNAL` 일시적으로 사용할 수 없음, 잠시 후 다시 시도하세요.
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
              description: HTTP 상태 코드
            message:
              type: string
            status:
              type: string
              description: 상태 값(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: >-
        ## 모든 엔드포인트는 Bearer Token 인증이 필요합니다


        **API Key 발급:**


        [API Key 관리](https://evolink.ai/dashboard/keys)에서 발급받으세요.


        **다음 요청 헤더 추가:**

        ```

        Authorization: Bearer YOUR_API_KEY

        ```


        Gemini 네이티브 형식인 `x-goog-api-key: YOUR_API_KEY` 헤더 또는 `?key=YOUR_API_KEY`
        URL 매개변수도 사용할 수 있습니다.

````

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