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 のうち少なくとも1つを指定してキャッシュを作成し、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 ヘッダー、または URL パラメータ ?key=YOUR_API_KEY も使用できます。
ボディ
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 が書き込み料金と保存料金の計算に用いるトークン数です