跳到主要内容

获取响应上下文

本接口用于获取某次模型响应对应的全部上下文信息。通过此接口，您可以检索指定响应的所有输入项，包括历史对话、工具调用等上下文元素。

开通服务​

  • 开发环境：直接创建 API Key 即可使用上下文缓存功能。
  • 生产环境：需要提交工单开通上下文缓存功能。
  • 使用前请确保您已获取 API Key。参见快速开始获取 API Key。

请求方法​

GET：<ai-api-base-url>/llm/v1/responses/{response_id}/input_items

其中，<ai-api-base-url> 为您的 API Key 所属数据中心的域名：

  • 北京数据中心：https://ai.rong-api.com
  • 北美数据中心：https://ai.us-light-api.com

请求头参数​

参数名类型必传默认值说明
Authorizationstring是-身份认证令牌，格式为 Bearer <your API key>，需替换为实际 API Key，用于验证用户权限。

路径参数​

参数名类型必传说明
response_idstring是待检索上下文元素所对应的响应 ID。

查询参数​

查询参数在 URL 中传入。

参数名类型必传默认值说明
afterstring/null否null返回该 ID 之后的输入项，用于分页。
beforestring/null否null返回该 ID 之前的输入项，用于分页。
limitinteger否100控制单次返回的最大项目数，取值范围：[1, 100]。
orderstring否desc控制输入项的排序方式。
  • asc：按照正序排列
  • desc：按照倒序排列
include[]array/null否null用于指定在响应中要额外包含的字段。部分接口默认返回基础字段，通过 include 可让服务端补充返回更多信息。
  • message.input_image.image_url：包含输入消息中的图像 URL。图像为 URL 时返回 URL，图像为 base64 编码时返回 base64 编码信息

请求示例​

bash
curl --location '<ai-api-base-url>/llm/v1/responses/resp_123456/input_items?limit=10&order=desc' \
  --header 'Authorization: Bearer <token>'

返回结果​

返回本次响应对应的所有上下文元素。

参数名类型说明
objectstring对象类型，固定为 list。
dataobject[]/null上下文元素列表，与创建模型响应时的 input（输入的元素列表）字段结构完全一致。如果请求中引用了 previous_response_id，服务器也会返回 previous_response 包含的上下文。
first_idstring列表中第一条数据的 ID。
last_idstring列表中最后一条数据的 ID。
has_moreboolean标识是否还有更多数据未返回。
  • true：存在未返回的数据
  • false：已返回全部数据

返回结果示例​

JSON
{
    "object": "list",
    "data": [
        {
            "type": "message",
            "role": "assistant",
            "content": [
                {
                    "type": "output_text",
                    "text": "融云的缓存机制可以显著降低 Token 消耗和提升响应速度。具体来说：\n\n**工作原理**：\n- 当您开启缓存（`caching: {\"type\": \"enabled\"}`）时，系统会自动缓存本次对话的上下文\n- 在后续多轮对话中，通过 `previous_response_id` 引用时，已缓存的内容无需重复计算\n- 缓存的 token 数量会在返回结果的 `usage.input_tokens_details.cached_tokens` 字段中显示\n\n**使用建议**：\n1. 适用于多轮对话场景，可大幅节省成本\n2. 缓存有效期最长 3 天，通过 `expire_at` 参数控制\n3. 注意：使用 `instructions` 参数会导致缓存失效\n\n**计费说明**：\n- 缓存存储按时长计费，不满 1 小时按 1 小时计算\n- 使用缓存的输入 token 成本远低于普通输入 token\n\n这样可以在保证对话质量的同时，有效控制 API 调用成本。"
                }
            ],
            "status": "completed",
            "id": "msg_0217****c3b2"
        },
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "缓存机制是如何工作的？"
                }
            ],
            "id": "msg_0217****b8f1"
        },
        {
            "type": "message",
            "role": "assistant",
            "content": [
                {
                    "type": "output_text",
                    "text": "融云 AI API 的工具调用功能非常强大，主要包括以下几类：\n\n**1. 自定义工具（Function Calling）**\n- 您可以定义自己的函数，让模型根据对话内容智能调用\n- 适用于查询数据库、调用业务接口等场景\n- 通过 JSON Schema 定义参数，确保类型安全\n\n**2. 内置工具**\n- **联网搜索**：让模型能够获取实时互联网信息\n- **图像处理**：支持画点、画线、旋转、缩放等图像操作\n- **私域知识库搜索**：检索您自己的知识库内容\n\n**3. MCP 工具**\n- 通过 MCP 协议集成第三方系统\n- 灵活的权限控制和工具选择\n\n**使用方式**：\n在请求中配置 `tools` 参数，模型会自动判断何时需要调用哪个工具。您可以通过 `tool_choice` 参数控制工具调用的策略。\n\n这些工具可以让 AI 应用具备更强的实用性和扩展性。"
                }
            ],
            "status": "completed",
            "id": "msg_0217****a7d3"
        },
        {
            "type": "message",
            "role": "user",
            "content": [
                {
                    "type": "input_text",
                    "text": "融云 AI API 支持哪些工具调用？"
                }
            ],
            "id": "msg_0217****92c4"
        }
    ],
    "first_id": "msg_****92c4",
    "last_id": "msg_****c3b2",
    "has_more": false
}

分页查询示例​

如果您需要分页查询大量上下文数据，可以使用 after 或 before 参数：

bash
# 获取前 10 条数据
curl '<ai-api-base-url>/llm/v1/responses/resp_123456/input_items?limit=10&order=desc' \
  --header 'Authorization: Bearer <token>'

# 获取 last_id 之后的 10 条数据
curl '<ai-api-base-url>/llm/v1/responses/resp_123456/input_items?limit=10&after=input_010' \
  --header 'Authorization: Bearer <token>'
最后于 更新