POST https://ark.cn-beijing.volces.com/api/v3/context/create 运行
上下文缓存（Context API）是方舟提供的一个高效的缓存机制。它通过缓存上下文数据，减少重复加载或处理，提高响应速度和一致性。本文介绍上下文缓存 API 的输入输出参数，供您使用接口时查阅字段含义。
请求参数#
跳转 响应参数
请求体#
model string 必选
通过 Endpoint ID 来调用模型，获得限流、计费类型（前付费/后付费）、运行状态查询、监控、安全等高级能力，可参考 获取 Endpoint ID。
暂不支持通过 Model ID 来调用。
messages object[] 必选
对话组成的消息列表。您希望缓存的信息。
注意：初始化的信息如系统人设，背景信息等，请使用系统消息（System message）放在消息列表最前。这部分信息在2种缓存模式下，均会一直存储在缓存中，直到缓存到期（触达最大生命周期）释放。
属性
系统消息 object
系统消息，开发人员提供的指令，模型应遵循这些指令。如模型扮演的角色或者目标等。
属性
messages.role string 必选
发送消息的角色，此处应为system。
messages.content string 必选
系统信息内容。
用户消息object
用户发送的消息，包含提示或附加上下文信息。
属性
messages.role string 必选
发送消息的角色，此处应为user。
messages.content string 必选
用户信息内容。
messages.name string
发送此消息的角色的姓名。用于区别同一个角色但是不同主体发送的消息。
模型消息 object
模型响应用户消息而回复的消息。
messages.role string 必选
发送消息的角色，此处应为assistant。
messages.content string
模型回复的消息。
messages.tool_calls object[]
模型回复的工具调用信息。
属性
messages.tool_calls.function object 必选
模型调用工具对应的函数信息。
属性
messages.tool_calls.function.name string 必选
模型需要调用的函数名称。
messages.tool_calls.function.arguments string 必选
模型生成的用于调用函数的参数，JSON 格式。
messages.tool_calls.id string 必选
调用的工具的 ID。
messages.tool_calls.type string 必选
工具类型，当前仅支持function。
mode string 默认值 session
本次请求创建的上下文缓存的类型。点此 了解类型介绍。点此 了解支持的模型 。
session：Session 缓存。common_prefix：前缀缓存。
ttl integer / null 默认值 86400
过期时长，单位为秒，设置范围：[3600, 604800]，即1小时到7天。
信息在创建后即开始计时，每次使用则重置为0。计时超过ttl，信息会被从缓存中删除。每次调用chat均根据ttl更新过期时间。
truncation_strategy object / null 默认值 null
缓存的上下文长度的窗口长度策略配置，只在当 mode 字段设置为session，该字段可设置。
支持 Session 缓存的模型能且只能支持 1 种 Session 缓存模式。如不配置该字段，方舟会根据您调用的模型自动适配合适的 Session 缓存模式。
属性
last_history_tokens 模式 object
触发缓存上限不会重新计算。
属性
truncation_strategy.type string 必选
此处应为 last_history_tokens。
truncation_strategy.last_history_tokens integer 默认值 4096
取值范围： (0,32768)。
缓存上下文窗口大小，即可缓存的上下文的最大 token 数。触发该上限将根据缓存上下文窗口大小对缓存内容进行清除。清除顺序按照信息被缓存时间长短排序，先清除缓存时间长的信息 。
rolling_tokens 模式 object
触发缓存上限会进行重新计算。
属性
truncation_strategy.type string 必选
此处应为 rolling_tokens。
truncation_strategy.rolling_tokens boolean 默认值 true
在缓存中历史消息长度接近 max_window_tokens 字段值时，是否自动对历史上下文进行裁剪（按照 message 元素粒度裁剪，按照 message 元素取整，即删除的信息的长度在 rolling_window_tokens 范围内，不会截断任意信息）。
false：在历史消息长度超过上下文长度时模型会停止输出（返回字段 finish_reason 为length)。true：在历史消息长度接近上下文长度时模型按照先进先出的顺序，自动删除定量（rolling_window_tokens 字段值 token 数）的内容，为新对话内容腾挪缓存空间；同时对缓存中的信息进行重新计算和读入，保障内容理解一致性。具体的计算逻辑，请参见 rolling_tokens 模式。
truncation_strategy.max_window_tokens integer / null 默认值 32768
在缓存中可存储的历史消息长度最大值。
取值满足下面条件：0 < rolling_window_tokens < max_window_tokens < context window（模型最大上下文）。
truncation_strategy.rolling_window_tokens integer / null 默认值 4096
当缓存触发了max_window_tokens 上限，则会裁剪滚动窗口长度。
取值满足下面条件：0 < rolling_window_tokens < max_window_tokens < context window（模型最大上下文）。
响应参数#
跳转 请求参数
id string
本次请求创建的上下文缓存的ID，在后续创建带缓存的 上下文缓存对话 API 需要使用。
model string
本次请求使用的推理接入点的 ID 。
mode string
本次请求创建的上下文缓存的类型。点此 了解支持的模型 。
session：Session 缓存。common_prefix：前缀缓存。
ttl integer
本次请求创建的上下文缓存过期时长，单位为秒。信息在创建后即开始计时，每次使用则重置为0。计时超过ttl，信息会被从缓存中删除。每次调用chat均根据ttl更新过期时间。
过期时间可以设置的范围在1小时到7天，即[3600, 604800]。
truncation_strategy object
本次请求创建的 Session 缓存使用的截断策略信息。
属性
last_history_tokens 模式 object
触发缓存上限，自动滚动缓存内容，无需重新计算。
属性
truncation_strategy.type string
本次请求创建的 Session 缓存的截断策略，此处应为 last_history_tokens。
truncation_strategy.last_history_tokens integer
本次请求创建的 Session 缓存可缓存的最大 token 数。
rolling_tokens 模式 object
触发缓存上限，进行重新计算。
属性
truncation_strategy.type string
本次请求创建的 Session 缓存的截断策略，此处应为 rolling_tokens。
truncation_strategy.rolling_tokens boolean
本次请求创建的 Session 缓存，当缓存的信息量达到最大缓存窗口时，是否自动处理。
usage object
本次请求的 token 用量。
属性
usage.prompt_tokens integer
输入的 prompt token 数量。
usage.completion_tokens integer
模型生成的 token 数量。
usage.total_tokens integer
本次请求消耗的总 token 数量（输入 + 输出）。
usage.prompt_tokens_details object
命中上下文缓存的 token 细节。
属性
usage.prompt_tokens_details.cached_tokens integer
命中上下文缓存的 token 数。