云开发 LLM API 支持协议介绍

云开发 CloudBase AI 支持以下协议：Chat Completions、Responses API、Anthropic Messages API，凡是支持自定义接口的 AI 工具都可以直接接入。

准备工作

已开通云开发环境，获取环境ID cloudBase环境ID
在 AI 控制台中开启所需模型
在 AI 控制台中获取 Base URL 和 API Key

codebuddy

Chat Completions

最通用的大模型对话协议，绝大多数 AI 工具默认使用此协议（OpenAI Compatible）。

以工具调用为例，完整流程需要两次 API 请求：

第一次请求：发送用户消息和可用工具定义

curl https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -d '{
    "model": "hy3-preview",
    "messages": [
      { "role": "user", "content": "帮我查一下北京今天的天气。" }
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "获取指定城市的天气预报",
          "parameters": {
            "type": "object",
            "properties": {
              "location": { "type": "string", "description": "城市名称" }
            },
            "required": ["location"]
          }
        }
      }
    ]
  }'

模型返回 finish_reason: "tool_calls"，表示需要客户端执行工具。客户端调用工具获取结果后，将工具返回值追加到 messages 中发起第二次请求：

第二次请求：携带工具调用结果

curl https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -d '{
    "model": "hy3-preview",
    "messages": [
      { "role": "user", "content": "帮我查一下北京今天的天气。" },
      {
        "role": "assistant",
        "tool_calls": [{
          "id": "call_123",
          "type": "function",
          "function": { "name": "get_current_weather", "arguments": "{\"location\": \"北京\"}" }
        }]
      },
      {
        "role": "tool",
        "tool_call_id": "call_123",
        "content": "{\"temperature\": \"25℃\", \"weather\": \"晴朗\"}"
      }
    ]
  }'

模型会根据工具返回的结果生成最终回复。

Responses API

OpenAI 推出的新一代 API，原生支持状态管理，通过 previous_response_id 串联多轮对话，无需客户端手动拼接历史消息。

第一次请求：发送用户消息和工具定义

curl "https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -d '{
    "model": "hy3-preview",
    "input": "请问今天北京的天气怎么样？",
    "tools": [
      {
        "type": "function",
        "name": "get_current_weather",
        "description": "获取指定城市的实时天气",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string", "description": "城市名称" }
          },
          "required": ["location"]
        }
      }
    ],
    "tool_choice": "auto"
  }'

模型返回 function_call 类型的 output，包含响应 ID（如 resp_xxx）。客户端调用工具后，通过 previous_response_id 串联上下文：

第二次请求：携带工具结果和 previous_response_id

curl "https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -d '{
    "model": "hy3-preview",
    "previous_response_id": "resp_570bc50971764d1fb1c167d90fc1a584",
    "input": [
      {
        "type": "function_call_output",
        "call_id": "call_abc",
        "output": "{\"temperature\": \"26°C\", \"condition\": \"晴朗\"}"
      }
    ]
  }'

备注

虽然 Responses API 在客户端只需传 previous_response_id 即可串联上下文，但服务端仍在维护完整的对话历史。

Anthropic Messages API

Anthropic（Claude 模型）的原生接口协议。

备注

云开发 CloudBase AI 使用 Authorization: Bearer 方式鉴权，而非 Anthropic 原生的 x-api-key 头。请求时需要携带 anthropic-version 头。

请求示例（带工具调用）：

curl "https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "hy3-preview",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "获取指定城市的实时天气",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "城市名称" }
          },
          "required": ["city"]
        }
      }
    ],
    "messages": [
      { "role": "user", "content": "请问今天北京的天气怎么样？" }
    ]
  }'

模型返回 stop_reason: "tool_use" 时，content 数组中会包含 type: "tool_use" 块，记录其中的 id 用于后续工具结果回传。

使用缓存

Anthropic Messages API 支持两种缓存模式：

显式缓存

在特定内容块末尾添加 "cache_control": {"type": "ephemeral"} 标记，每个请求最多设置 4 个断点。适合需要精确控制缓存位置的场景：

curl "https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "hy3-preview",
    "max_tokens": 1024,
    "system": [
      {
        "type": "text",
        "text": "你是一个专业的天气查询助手。",
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "tools": [
      {
        "name": "get_weather",
        "description": "获取指定城市的实时天气",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "城市名称" }
          },
          "required": ["city"]
        },
        "cache_control": {"type": "ephemeral"}
      }
    ],
    "messages": [
      { "role": "user", "content": "请问今天北京的天气怎么样？" }
    ]
  }'

自动缓存

在请求体最外层声明 "cache_control": {"type": "ephemeral"}，系统自动识别重复的静态前缀进行缓存，适合多轮对话场景：

curl "https://{{YOUR-ENV-ID}}.api.tcloudbasegateway.com/v1/ai/cloudbase/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {{YOUR-API-KEY}}" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "hy3-preview",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "你是一个专业的天气查询助手。",
    "tools": [
      {
        "name": "get_weather",
        "description": "获取指定城市的实时天气",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "城市名称" }
          },
          "required": ["city"]
        }
      }
    ],
    "messages": [
      { "role": "user", "content": "请问今天北京的天气怎么样？" }
    ]
  }'

准备工作​

Chat Completions​

Responses API​

Anthropic Messages API​

使用缓存​

显式缓存​

自动缓存​