curl --request POST \
--url https://direct.evolink.ai/v1beta/cachedContents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "models/gemini-3.8-flash",
"displayName": "product-manual-v3",
"systemInstruction": {
"parts": [
{
"text": "제품 설명서 도우미입니다. 제공된 설명서에만 근거해 답하고, 없는 정보는 \"설명서에 언급되지 않았습니다\"라고 답하세요."
}
]
},
"contents": [
{
"role": "user",
"parts": [
{
"text": "(제품 설명서 전문을 여기에 넣으세요. 캐시 내용은 최소 4,096토큰이어야 합니다.)"
}
]
}
],
"ttl": "3600s"
}
'{
"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
}
}{
"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"
}
]
}
}{
"error": {
"code": 401,
"message": "Invalid API key",
"status": "UNAUTHENTICATED"
}
}{
"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"
}
]
}
}{
"error": {
"code": 403,
"message": "This key is not allowed to use model gemini-3.8-flash",
"status": "PERMISSION_DENIED"
}
}{
"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"
}
]
}
}{
"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"
}
]
}
}{
"error": {
"code": 429,
"message": "Rate limit exceeded",
"status": "RESOURCE_EXHAUSTED"
}
}{
"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"
}
]
}
}{
"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"
}
]
}
}명시적 컨텍스트 캐싱
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가 선언되어 있으면 검색마다 별도로 과금됩니다. 단축·삭제·만료 시 저장 요금은 환불되지 않으며, 연장 시 추가 기간분을 청구합니다. 모델별 단가는 가격 페이지를 참고하세요.
Authorization: Bearer로 인증하며 x-goog-api-key 헤더도 허용합니다.
POST
/
v1beta
/
cachedContents
curl --request POST \
--url https://direct.evolink.ai/v1beta/cachedContents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "models/gemini-3.8-flash",
"displayName": "product-manual-v3",
"systemInstruction": {
"parts": [
{
"text": "제품 설명서 도우미입니다. 제공된 설명서에만 근거해 답하고, 없는 정보는 \"설명서에 언급되지 않았습니다\"라고 답하세요."
}
]
},
"contents": [
{
"role": "user",
"parts": [
{
"text": "(제품 설명서 전문을 여기에 넣으세요. 캐시 내용은 최소 4,096토큰이어야 합니다.)"
}
]
}
],
"ttl": "3600s"
}
'{
"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
}
}{
"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"
}
]
}
}{
"error": {
"code": 401,
"message": "Invalid API key",
"status": "UNAUTHENTICATED"
}
}{
"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"
}
]
}
}{
"error": {
"code": 403,
"message": "This key is not allowed to use model gemini-3.8-flash",
"status": "PERMISSION_DENIED"
}
}{
"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"
}
]
}
}{
"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"
}
]
}
}{
"error": {
"code": 429,
"message": "Rate limit exceeded",
"status": "RESOURCE_EXHAUSTED"
}
}{
"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"
}
]
}
}{
"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"
}
]
}
}BaseURL: 기본 BaseURL은
https://direct.evolink.ai이며, 텍스트 모델 지원이 더 우수하고 장시간 연결을 지원합니다. https://api.evolink.ai는 멀티모달 서비스의 주력 엔드포인트이며, 텍스트 모델에 대해서는 대체 주소로 사용됩니다.명시적 컨텍스트 캐싱: 반복해서 사용하는 긴 프리픽스(긴 문서, 시스템 지침, 도구 정의)를 캐시로 생성하면 이후 생성 요청에는 캐시 이름과 새 질문만 보내면 됩니다. 캐시 토큰은 캐시 적중 단가로 과금됩니다. 별도로 캐시 쓰기 요금과 시간 단위 저장 요금이 발생하며, 저장 요금은 생성 시 전체 유효 기간분을 청구하고 환불되지 않습니다.
캐시 참조:
generateContent 또는 streamGenerateContent 요청 본문에 "cachedContent": "<name>"을 추가하고 contents에는 새 질문만 넣습니다. 캐시를 참조하는 요청에는 systemInstruction, tools, toolConfig를 포함할 수 없으며, 캐시 생성 시와 같은 모델을 사용해야 합니다.인증
모든 엔드포인트는 Bearer Token 인증이 필요합니다
API Key 발급:
API Key 관리에서 발급받으세요.
다음 요청 헤더 추가:
Authorization: Bearer YOUR_API_KEY
Gemini 네이티브 형식인 x-goog-api-key: YOUR_API_KEY 헤더 또는 ?key=YOUR_API_KEY URL 매개변수도 사용할 수 있습니다.
본문
application/json
모델. 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
예시:
"models/gemini-3.8-flash"
응답
캐시가 생성되었습니다. usageMetadata.totalTokenCount는 쓰기 및 저장 요금 계산에 사용하는 캐시 토큰 수입니다