1.概述

显示创建上下文缓存，通过本接口获得缓存id字段后，在对话生成接口中通过携带context_id使用。

模型列表：

  • gemini-2.0-flash
  • gemini-2.5-flash
  • gemini-2.5-pro
  • gemini-2.5-flash-lite
  • gemini-2.5-flash-lite-preview-06-17
  • gemini-2.5-flash-thinking (输出思考过程)
  • gemini-2.5-pro-thinking (输出思考过程)
  • gemini-3-pro-preview

2.请求说明

  • 请求方法: POST
  • 请求地址
  https://gateway.theturbo.ai/v1/context/create

3.请求参数

3.1 Head参数

参数名称 类型 必填 说明 示例值
Content-Type string 是 设置请求头类型，必须为application/json application/json
Accept string 是 设置响应类型，建议统一为application/json application/json
Authorization string 是 身份验证所需的 API_KEY，格式Bearer $YOUR_API_KEY Bearer $YOUR_API_KEY

3.2 Body 参数 (application/json)

参数名称 类型 必填 说明 示例
model string 是 要使用的模型 ID。详见概述列出的可用版本，如 gemini-2.0-flash。 gemini-2.0-flash
messages array 是
用于初始化或希望服务在缓存中存储的信息，格式与 OpenAI 兼容。数组中的每个对象包含 role(角色) 与 content(内容)。 [{"role": "system","content": "you are a helpful asssistant"}]
role string 否 消息角色，可选值: system、user、assistant。 system
content string 否 消息的具体内容。 you are a helpful asssistant
ttl number 否 过期时长，单位为秒。 300

4.请求示例 

  POST /v1/context/create
Content-Type: application/json
Accept: application/json
Authorization: Bearer $YOUR_API_KEY

{
	"model": "gemini-2.0-flash",
	"messages": [
		{
			"role": "system",
			"content": "请扮演一位友好的客服。... 不少于4096tokens ..."
		},
		{
			"role": "user",
			"content": "你好"
		}
	],
	"ttl": 300
}
  
  curl https://gateway.theturbo.ai/v1/context/create \
	-H "Content-Type: application/json" \
	-H "Accept: application/json" \
	-H "Authorization: Bearer $YOUR_API_KEY" \
	-d "{
	\"model\": \"gemini-2.0-flash\",
	\"messages\": [{
			\"role\": \"system\",
			\"content\": \"请扮演一位友好的客服。... 不少于4096tokens ...\"
		},
		{
			\"role\": \"user\",
			\"content\": \"你好\"
		}
	],
	\"ttl\": 300
}"
  
  package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
	"strings"
)

const (
	YOUR_API_KEY    = "sk-123456789012345678901234567890123456789012345678"
	REQUEST_PAYLOAD = `{
	"model": "gemini-2.0-flash",
	"messages": [{
			"role": "system",
			"content": "请扮演一位友好的客服。... 不少于4096tokens ..."
		},
		{
			"role": "user",
			"content": "你好"
		}
	],
	"mode": "session",
	"ttl": 3600
}`
)

func main() {

	requestURL := "https://gateway.theturbo.ai/v1/context/create"
	requestMethod := "POST"
	requestPayload := strings.NewReader(REQUEST_PAYLOAD)

	req, err := http.NewRequest(requestMethod, requestURL, requestPayload)
	if err != nil {
		fmt.Println("Create request failed, err: ", err)
		return
	}

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Accept", "application/json")
	req.Header.Add("Authorization", "Bearer "+YOUR_API_KEY)

	client := &http.Client{}

	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("Do request failed, err: ", err)
		return
	}
	defer resp.Body.Close()

	respBodyBytes, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("Read response body failed, err: ", err)
		return
	}
	fmt.Println(string(respBodyBytes))
}

5.响应示例 

  {
	"id": "projects/37021971161/locations/global/cachedContents/1692176707571679232",
	"ttl": 300,
	"usage": {
		"prompt_tokens": 4375,
		"completion_tokens": 0,
		"total_tokens": 0,
		"cache_creation_input_tokens": 4375
	}
}