# 上下文缓存对话创建

## 1. 概述

创建上下文缓存，通过本接口获得缓存`id`字段后，在[上下文缓存对话生成](https://docs.console.zenlayer.com/api/cn/compute/aig/chat-completion/doubao/doubao-context-chat-completion)接口中通过携带`context_id`使用。

**模型列表：**

* `Doubao-1.5-pro-32k`
* `Doubao-1.5-lite-32k`
* `Doubao-pro-32k`

## 2. 请求说明

* **请求方法**:`POST`
* **请求地址**:

  > `https://gateway.theturbo.ai/v1/context/create`

***

## 3. 请求参数

### 3.1 Header 参数

| 参数名称            | 类型     | 必填 | 说明                                         | 示例值                    |
| --------------- | ------ | -- | ------------------------------------------ | ---------------------- |
| `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。详见[概述](#1-概述)列出的可用版本，如 `Doubao-1.5-pro-32k`。                                                                          | `Doubao-1.5-pro-32k`                                             |
| **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`                                   |
| mode         | string | 否  | 上下文缓存的类型，详细见官方文档[上下文缓存（Context API）概述](https://www.volcengine.com/docs/82379/1398933)。支持session缓存`session`和前缀缓存`common_prefix`。 | `session`                                                        |
| ttl          | number | 否  | 过期时长，单位为秒。信息在创建后即开始计时，每次使用则重置为0。计时超过ttl，信息会被从缓存中删除。每次调用chat均根据ttl更新过期时间。过期时间可以设置的范围在1小时到7天，即\[3600, 604800]。                    | `86400`                                                          |

***

## 4. 请求示例

{% tabs %}
{% tab title="HTTP" %}

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

{
	"model": "Doubao-1.5-pro-32k",
	"messages": [
		{
			"role": "system",
			"content": "请扮演一位友好的客服"
		},
		{
			"role": "user",
			"content": "你好"
		}
	],
	"mode":"session",
	"ttl": 3600
}
```

{% endtab %}

{% tab title="Shell" %}

```sh
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\": \"Doubao-1.5-pro-32k\",
	\"messages\": [{
			\"role\": \"system\",
			\"content\": \"请扮演一位友好的客服\"
		},
		{
			\"role\": \"user\",
			\"content\": \"你好\"
		}
	],
	\"mode\": \"session\",
	\"ttl\": 3600
}"
```

{% endtab %}

{% tab title="Go" %}

```go
package main

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

const (
	YOUR_API_KEY    = "sk-123456789012345678901234567890123456789012345678"
	REQUEST_PAYLOAD = `{
	"model": "Doubao-1.5-pro-32k",
	"messages": [{
			"role": "system",
			"content": "请扮演一位友好的客服"
		},
		{
			"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))
}
```

{% endtab %}
{% endtabs %}

## 5. 响应示例

```json
{
	"id": "ctx-20241211104333-12345",
	"ttl": 3600,
	"truncation_strategy": {
		"type": "rolling_tokens",
		"rolling_tokens": true
	},
	"usage": {
		"prompt_tokens": 8,
		"completion_tokens": 0,
		"total_tokens": 8,
		"prompt_tokens_details": {
			"cached_tokens": 0
		}
	},
	"mode": "session"
}
```
