> ## 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 명시적 컨텍스트 캐싱 - 캐시 생성

> `contents`, `systemInstruction`, `tools` 중 하나 이상으로 캐시를 생성하고 이름 `name`을 받습니다. `toolConfig`도 추가할 수 있습니다.

- **모델**: `model`은 `models/gemini-3.8-flash` 또는 `gemini-3.8-flash` 형식을 모두 허용합니다. 지원 모델은 `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`입니다. Gemini 4는 명시적 캐시를 지원하지 않습니다.
- **유효 기간**: `ttl`(예: `"3600s"`) 또는 `expireTime`(RFC 3339) 중 하나만 지정합니다. 둘 다 생략하면 1시간입니다. 최소 60초, 최대 168시간(`604800s`)이며 만료 시 자동 삭제됩니다.
- **크기**: 요청 본문은 최대 10 MB입니다. 모델의 최소 캐시 토큰 수(예: `gemini-3.8-flash`는 4,096)에 미달하면 400을 반환합니다.
- **필드**: 문서에 나열된 필드만 허용하며 나머지는 400을 반환합니다.
- **tools**: `googleSearch`, `codeExecution`, `functionDeclarations`만 허용하며 나머지 도구는 400을 반환합니다.
- **반환되는 `name`**: `cachedContents/<id>` 형식이며 `<id>`는 생성 요청 ID입니다. 대시보드의 로그 페이지에서 검색하면 생성 요금을 확인할 수 있습니다.
- **요금**: 생성 시 캐시 쓰기 요금(입력 단가와 동일)과 전체 유효 기간의 저장 요금(100만 토큰·1시간당)을 선불로 청구합니다. 캐시를 참조하는 요청에서는 캐시 토큰이 캐시 적중 단가로 과금되며, 캐시에 `googleSearch`가 선언되어 있으면 검색마다 별도로 과금됩니다. 단축·삭제·만료 시 저장 요금은 환불되지 않으며, 연장 시 추가 기간분을 청구합니다. 모델별 단가는 [가격 페이지](https://evolink.ai/pricing)를 참고하세요.

`Authorization: Bearer`로 인증하며 `x-goog-api-key` 헤더도 허용합니다.

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

> [!NOTE]
>
> **명시적 컨텍스트 캐싱**: 반복해서 사용하는 긴 프리픽스(긴 문서, 시스템 지침, 도구 정의)를 캐시로 생성하면 이후 생성 요청에는 캐시 이름과 새 질문만 보내면 됩니다. 캐시 토큰은 캐시 적중 단가로 과금됩니다. 별도로 캐시 쓰기 요금과 시간 단위 저장 요금이 발생하며, 저장 요금은 생성 시 전체 유효 기간분을 청구하고 환불되지 않습니다.

> [!TIP]
>
> **캐시 참조**: `generateContent` 또는 `streamGenerateContent` 요청 본문에 `"cachedContent": "<name>"`을 추가하고 `contents`에는 새 질문만 넣습니다. 캐시를 참조하는 요청에는 `systemInstruction`, `tools`, `toolConfig`를 포함할 수 없으며, 캐시 생성 시와 같은 모델을 사용해야 합니다.


## OpenAPI

````yaml ko/api-manual/language-series/gemini/cached-contents/cached-contents.json POST /v1beta/cachedContents
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:
    post:
      tags:
        - 명시적 컨텍스트 캐싱
      summary: 캐시 생성
      description: >-
        `contents`, `systemInstruction`, `tools` 중 하나 이상으로 캐시를 생성하고 이름 `name`을
        받습니다. `toolConfig`도 추가할 수 있습니다.


        - **모델**: `model`은 `models/gemini-3.8-flash` 또는 `gemini-3.8-flash` 형식을
        모두 허용합니다. 지원 모델은 `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`입니다. Gemini 4는 명시적 캐시를 지원하지 않습니다.

        - **유효 기간**: `ttl`(예: `"3600s"`) 또는 `expireTime`(RFC 3339) 중 하나만 지정합니다.
        둘 다 생략하면 1시간입니다. 최소 60초, 최대 168시간(`604800s`)이며 만료 시 자동 삭제됩니다.

        - **크기**: 요청 본문은 최대 10 MB입니다. 모델의 최소 캐시 토큰 수(예: `gemini-3.8-flash`는
        4,096)에 미달하면 400을 반환합니다.

        - **필드**: 문서에 나열된 필드만 허용하며 나머지는 400을 반환합니다.

        - **tools**: `googleSearch`, `codeExecution`, `functionDeclarations`만
        허용하며 나머지 도구는 400을 반환합니다.

        - **반환되는 `name`**: `cachedContents/<id>` 형식이며 `<id>`는 생성 요청 ID입니다. 대시보드의
        로그 페이지에서 검색하면 생성 요금을 확인할 수 있습니다.

        - **요금**: 생성 시 캐시 쓰기 요금(입력 단가와 동일)과 전체 유효 기간의 저장 요금(100만 토큰·1시간당)을 선불로
        청구합니다. 캐시를 참조하는 요청에서는 캐시 토큰이 캐시 적중 단가로 과금되며, 캐시에 `googleSearch`가 선언되어
        있으면 검색마다 별도로 과금됩니다. 단축·삭제·만료 시 저장 요금은 환불되지 않으며, 연장 시 추가 기간분을 청구합니다. 모델별
        단가는 [가격 페이지](https://evolink.ai/pricing)를 참고하세요.


        `Authorization: Bearer`로 인증하며 `x-goog-api-key` 헤더도 허용합니다.
      operationId: geminiCreateCachedContent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCachedContentRequest'
            examples:
              long_document:
                summary: 긴 문서와 시스템 지침을 1시간 캐시
                value:
                  model: models/gemini-3.8-flash
                  displayName: product-manual-v3
                  systemInstruction:
                    parts:
                      - text: >-
                          제품 설명서 도우미입니다. 제공된 설명서에만 근거해 답하고, 없는 정보는 "설명서에 언급되지
                          않았습니다"라고 답하세요.
                  contents:
                    - role: user
                      parts:
                        - text: (제품 설명서 전문을 여기에 넣으세요. 캐시 내용은 최소 4,096토큰이어야 합니다.)
                  ttl: 3600s
              with_tools:
                summary: 시스템 지침과 함수 정의를 절대 만료 시각으로 캐시
                value:
                  model: gemini-3.8-flash
                  displayName: support-agent-tools
                  systemInstruction:
                    parts:
                      - text: (최소 4,096토큰의 긴 고객 지원 지침을 여기에 넣으세요.)
                  contents:
                    - role: user
                      parts:
                        - text: (이전 지원 티켓 예시…)
                  tools:
                    - functionDeclarations:
                        - name: lookup_order
                          description: 주문 번호로 주문 상태 조회
                          parameters:
                            type: object
                            properties:
                              order_id:
                                type: string
                            required:
                              - order_id
                  expireTime: '2026-11-03T06:00:00Z'
      responses:
        '200':
          description: >-
            캐시가 생성되었습니다. `usageMetadata.totalTokenCount`는 쓰기 및 저장 요금 계산에 사용하는 캐시
            토큰 수입니다
          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: 잘못된 매개변수, 명시적 캐시 미지원 모델, 현재 사용자 그룹에 미개방, 또는 최소 캐시 토큰 수 미달
          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가 없거나 유효하지 않음
          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 prepayment
                  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: 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: 요청 본문이 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: 요청 빈도 제한 초과
          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: 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: >-
            모델. `models/gemini-3.8-flash`와 `gemini-3.8-flash` 모두 허용. 지원 모델:
            `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: >-
            캐시할 대화 내용. 배열이어야 하며 참조 시 대화 접두사가 됩니다. `contents`,
            `systemInstruction`, `tools` 중 하나 이상 필요
          items:
            $ref: '#/components/schemas/Content'
        systemInstruction:
          $ref: '#/components/schemas/Content'
          description: 시스템 지침. 캐시한 뒤에는 이를 참조하는 생성 요청에 systemInstruction을 넣을 수 없습니다
        tools:
          type: array
          description: 도구 선언. 캐시한 뒤에는 이를 참조하는 생성 요청에 tools를 넣을 수 없습니다
          items:
            $ref: '#/components/schemas/Tool'
        toolConfig:
          type: object
          description: >-
            도구 호출 설정(functionCallingConfig 등). 캐시한 뒤에는 이를 참조하는 생성 요청에
            toolConfig를 넣을 수 없습니다
        ttl:
          type: string
          description: >-
            유효 기간(예: `"3600s"`). 최소 `60s`, 최대 `604800s`(168시간). expireTime과 상호
            배타적이며 동시 지정은 400. 둘 다 생략하면 `3600s`
          example: 3600s
        expireTime:
          type: string
          format: date-time
          description: 절대 만료 시각(RFC 3339, UTC). ttl과 상호 배타적이며 동시 지정은 400
          example: '2026-11-03T06:00:00Z'
        displayName:
          type: string
          maxLength: 255
          description: 관리용 이름. 최대 255자이며 요금에 영향 없음
          example: product-manual-v3
    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
    Content:
      type: object
      required:
        - parts
      properties:
        role:
          type: string
          enum:
            - user
            - model
          description: 역할. 시스템 지침에는 필요 없음
        parts:
          type: array
          items:
            $ref: '#/components/schemas/Part'
    Tool:
      type: object
      description: 도구 선언. 아래 세 종류만 허용하며 다른 도구는 거부됩니다
      properties:
        googleSearch:
          type: object
          description: 웹 검색. `{}` 지정
        codeExecution:
          type: object
          description: 코드 실행. `{}` 지정
        functionDeclarations:
          type: array
          description: 함수 선언(OpenAPI 하위 집합의 매개변수 구조)
          items:
            type: object
            properties:
              name:
                type: string
              description:
                type: string
              parameters:
                type: object
    Part:
      type: object
      description: '콘텐츠 부분: 텍스트, 인라인 데이터(base64), 파일 참조 중 하나'
      properties:
        text:
          type: string
          description: 텍스트
        inlineData:
          type: object
          description: 인라인 바이너리 데이터(이미지, 오디오, PDF 등)
          properties:
            mimeType:
              type: string
              example: application/pdf
            data:
              type: string
              description: base64로 인코딩된 데이터
        fileData:
          type: object
          description: 파일 참조
          properties:
            mimeType:
              type: string
            fileUri:
              type: string
              description: 공개 접근 가능한 URL
  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.