POST/v1/messages

Claude：工具调用、结果回传与流式参数

声明客户端工具，执行受控函数并回传 tool_result，了解流式参数拼接。

API Key application/json

功能与适用场景

模型返回 tool_use，由应用执行对应业务函数，再以 tool_result 继续对话。示例工具只返回标明为示例的固定天气，不访问真实服务。

支持模型与组合

claude-sonnet-5。默认由模型决定是否调用工具；若直接返回文字，按普通回答处理。

第一步：设置鉴权

使用青云TOP API 的 API Key：Authorization: Bearer YOUR_API_KEY。替换占位符，保留 Bearer 后的空格。无需厂商 API Key。同时发送 anthropic-version: 2023-06-01。

第二步：调用模型

POST https://top.qingyuntop.ai/v1/messages

请求为 application/json。

Request

请求

/v1/messages

Body

必填

Bodyobject

modelstring必填

必填，顶层，准确模型 ID。示例 claude-sonnet-5；不要把 -thinking 后缀当成所有官方模型的通用命名。

messagesarray必填

必填，顶层，user / assistant 历史数组。content 可为文字或内容块数组；system 指令放顶层 system。

元素object

数组元素。

rolestring必填

可选：user / assistant

contentstring | array<object>必填

分支：string / array<object>

temperaturenumber

选填字段；是否可用取决于当前模型和协议。；范围：0–1

top_pnumber

选填字段；是否可用取决于当前模型和协议。

ninteger

默认为 1 为每个输入消息生成多少个聊天补全选择。

streamboolean

选填，默认 false。true 返回具名 SSE 事件；必须继续检查流中的 error。

stopstring

默认为 null 最多 4 个序列,API 将停止进一步生成标记。

max_tokensinteger必填

必填，顶层，正整数。限制输出 token（包含思考）；示例 4096。不要依赖接口为缺失值补默认。；范围：1–∞

presence_penaltynumber

-2.0 和 2.0 之间的数字。正值会根据到目前为止是否出现在文本中来惩罚新标记，从而增加模型谈论新主题的可能性。 [查看有关频率和存在惩罚的更多信息。](https://platform.openai.com/docs/api-reference/parameter-details)

frequency_penaltynumber

默认为 0 -2.0 到 2.0 之间的数字。正值根据文本目前的存在频率惩罚新标记,降低模型重复相同行的可能性。有关频率和存在惩罚的更多信息。

logit_biasnull

修改指定标记出现在补全中的可能性。接受一个 JSON 对象,该对象将标记(由标记器指定的标记 ID)映射到相关的偏差值(-100 到 100)。从数学上讲,偏差在对模型进行采样之前添加到模型生成的 logit 中。确切效果因模型而异,但-1 和 1 之间的值应减少或增加相关标记的选择可能性;如-100 或 100 这样的值应导致相关标记的禁用或独占选择。

userstring

代表您的最终用户的唯一标识符，可以帮助 OpenAI 监控和检测滥用行为。[了解更多](https://platform.openai.com/docs/guides/safety-best-practices/end-user-ids)。

response_formatobject

指定模型必须输出的格式的对象。将 { "type": "json_object" } 启用 JSON 模式,这可以确保模型生成的消息是有效的 JSON。重要提示:使用 JSON 模式时,还必须通过系统或用户消息指示模型生成 JSON。如果不这样做,模型可能会生成无休止的空白流,直到生成达到令牌限制,从而导致延迟增加和请求“卡住”的外观。另请注意,如果 finish_reason="length",则消息内容可能会被部分切断,这表示生成超过了 max_tokens 或对话超过了最大上下文长度。显示属性

seeninteger

此功能处于测试阶段。如果指定,我们的系统将尽最大努力确定性地进行采样,以便使用相同的种子和参数进行重复请求应返回相同的结果。不能保证确定性,您应该参考 system_fingerprint 响应参数来监控后端的更改。

toolsarray

选填，顶层工具数组。客户端函数使用 name、description、input_schema；服务器搜索工具另有 type。

元素object

数组元素。

tool_choiceobject

选填，对象。auto 让模型选择；type=tool 加 name 指定函数。强制工具模式与某些思考模式不兼容，示例不混用。；分支：object

systemstring | array<object>

选填，顶层，无默认值。字符串或文本块数组，不使用 role=system 消息。；分支：string / array<object>

cache_controlobject

选填字段；是否可用取决于当前模型和协议。

inference_geostring

选填字段；是否可用取决于当前模型和协议。

top_kinteger

选填字段；是否可用取决于当前模型和协议。

stop_sequencesarray<string>

选填字段；是否可用取决于当前模型和协议。

元素string

数组元素。

thinkingobject

选填，对象。Claude 4.6 及更高型号优先使用 type=adaptive；Claude 4.7 及更高型号拒绝 type=enabled。Claude 4.5 及更早型号使用 type=enabled，并填写 budget_tokens。budget_tokens 必须至少 1024 且小于 max_tokens。display 可填 summarized 或 omitted；updates 为 beta 能力，普通请求不要依赖它。工具多轮必须原样保留 thinking/redacted_thinking 块及 signature。

typestring

思考模式；可用值取决于模型。；可选：adaptive / enabled / disabled

budget_tokensinteger

手动思考目标预算，至少 1024，通常必须小于 max_tokens。；范围：1024–∞

displaystring

思考内容显示方式；updates 为 beta 能力。；可选：summarized / omitted / updates

context_managementobject

选填字段；是否可用取决于当前模型和协议。

output_configobject

选填，顶层对象。format 设置结构化输出；effort 设置支持模型的思考强度。不要继续使用早期 output_format 写法。

effortstring

思考强度；具体模型支持的等级不同。选填。可用等级为 low / medium / high / xhigh / max，但具体模型支持范围不同；Claude Fable/Mythos 5.x 支持完整五档，其他型号以模型说明为准。Claude 4.6 及更高型号优先使用 effort 配合 adaptive；Claude 4.5 的 effort 仅在官方支持的型号上与 enabled + budget_tokens 配合。Haiku 4.5 不要发送 effort。；可选：low / medium / high / xhigh / max

formatobject

结构化输出格式。结构化输出时填写 type=json_schema、schema；schema 根对象列出 properties / required，并用 additionalProperties=false。不与引文输出混用。

typestring必填

可选：json_schema

schemaobject必填

标准 JSON Schema；请按官方结构化输出限制定义。

output_formatobject

选填字段；是否可用取决于当前模型和协议。

containerstring | object

选填字段；是否可用取决于当前模型和协议。；分支：string / object

mcp_serversarray<object>

选填字段；是否可用取决于当前模型和协议。

元素object

数组元素。

metadataobject

选填字段；是否可用取决于当前模型和协议。

user_idstring

speedstring

选填字段；是否可用取决于当前模型和协议。；可选：standard / fast

service_tierstring

选填字段；是否可用取决于当前模型和协议。；可选：auto / standard_only

路径、查询与 Header 参数

参数	位置	类型	必填	说明	示例
`Content-Type`	Header	string	是	-	application/json
`Accept`	Header	string	是	-	application/json
`Authorization`	Header	string	是	必填。使用青云TOP API 的 API Key，保留 Bearer 后的空格。	Bearer YOUR_API_KEY

请求示例application/json

set -euo pipefail
python3 - <<'PY'
import base64
import json
from pathlib import Path

payload = json.loads(r'''{
  "model": "claude-sonnet-5",
  "max_tokens": 4096,
  "messages": [
    {
      "role": "user",
      "content": "请查询北京天气。"
    }
  ],
  "tools": [
    {
      "name": "get_weather",
      "description": "查询给定城市的天气；示例仅支持北京。",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "enum": [
              "北京"
            ]
          }
        },
        "required": [
          "city"
        ],
        "additionalProperties": false
      }
    }
  ],
  "system": "你是一个简洁、准确的 API 文档助手。"
}''')
encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
Path("request.json").write_bytes(encoded)
PY
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  --data-binary @request.json \
  --output response.json

Response

返回响应 `200`

HTTP 响应

响应 200object

idstring必填

objectstring必填

createdinteger必填

choicesarray<object>必填

元素object

indexinteger

messageobject

rolestring必填

contentarray必填

内容块数组。按 type 识别 text / thinking / tool_use 等，不只取 content[0].text。

finish_reasonstring

usageobject必填

输入与输出 token 用量；缓存与搜索细分字段按实际响应读取。

prompt_tokensinteger必填

completion_tokensinteger必填

total_tokensinteger必填

input_tokensinteger

output_tokensinteger

cache_creation_input_tokensinteger

cache_read_input_tokensinteger

contentarray

内容块数组。按 type 识别 text / thinking / tool_use 等，不只取 content[0].text。

元素object

数组元素。

typestring

textstring

stop_reasonstring

可为空。end_turn 为正常结束，tool_use 需要工具回传，max_tokens 表示截断；还可能有 stop_sequence / pause_turn / refusal。；可选：end_turn / max_tokens / stop_sequence / tool_use

响应示例json

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "\n\nHello there, how may I assist you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 12,
    "total_tokens": 21
  }
}

执行示例函数并回传

以下代码读取上一段的真实 tool_use.id，校验北京这一允许参数，保留完整 assistant 内容块、签名和工具声明后回传。若下一轮继续返回 tool_use，仍需按同一流程校验并处理，不能把它当作最终文字。

set -euo pipefail
python3 - <<'PY'
import base64
import json
from pathlib import Path

payload = json.loads(r'''{
  "model": "claude-sonnet-5",
  "max_tokens": 4096,
  "messages": []
}''')
previous = json.loads(Path("request.json").read_text(encoding="utf-8"))
result = json.loads(Path("response.json").read_text(encoding="utf-8"))
blocks = result["content"]
replies = []
for block in blocks:
    if block.get("type") != "tool_use":
        continue
    if block["name"] != "get_weather" or block["input"].get("city") != "北京":
        raise ValueError("工具名称或参数不在示例白名单中")
    replies.append({"type": "tool_result", "tool_use_id": block["id"], "content": "北京22摄氏度（示例数据）"})
if not replies:
    raise RuntimeError("本轮没有工具调用")
payload["messages"] = previous["messages"] + [{"role": "assistant", "content": blocks}, {"role": "user", "content": replies}]
payload["tools"] = previous["tools"]
if "system" in previous:
    payload["system"] = previous["system"]
encoded = json.dumps(payload, ensure_ascii=False).encode("utf-8")
Path("next-request.json").write_bytes(encoded)
PY
curl --fail-with-body --connect-timeout 30 --max-time 600 "https://top.qingyuntop.ai/v1/messages" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  --data-binary @next-request.json \
  --output next-response.json

常见错误与参考

tool_result 放在 user 内容数组，不能写成 OpenAI role=tool。不能只回传最后一个工具结果，或从模型输入动态执行任意函数名。

401：检查本站 API Key 和 Bearer 格式；403：确认此 Key 可用该模型；429：遵循 Retry-After 退避。超时或 5xx 时保留请求标识和脱敏错误，避免盲目重发；其他通用排查见聊天接入总览。

Claude 工具调用。

Claude：工具调用、结果回传与流式参数

功能与适用场景

支持模型与组合

第一步：设置鉴权

第二步：调用模型

请求

Body

路径、查询与 Header 参数

返回响应 200

执行示例函数并回传

常见错误与参考

返回响应 `200`