Claude Messages
使用 Claude Messages 请求格式。需选择公开目录标注 Anthropic 协议的模型。
/v1/messagesHeaders请求头
左右滑动查看完整参数表
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
Authorization | string | 必填 | 平台 API Key,使用 Bearer 认证。 | |
Content-Type | string | 必填 | 请求体编码格式。 | |
anthropic-version | string | 必填 | Anthropic API 版本。 |
Request Body请求体
application/json左右滑动查看完整参数表
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
model | string | 必填 | 模型 ID;请替换为账户可用且支持当前接口的模型。 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
messages | array<object> | 必填 | 对话历史;系统提示使用顶层 system 字段。 | — | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
role | string | 必填 | 消息角色。 可选值 userassistant | — | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
content | string | array<object> | 必填 | 文本或按顺序排列的内容块。 | — | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | string | 必填 | 内容块类型;不同类型使用对应字段。 可选值 textimagetool_usetool_resultthinkingredacted_thinking | — | |||||||||||||||||||||||||
text | string | 可选 | type=text 时的文本。 | — | |||||||||||||||||||||||||
source | object | 可选 | 图片内容来源。 | — | |||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
type | string | 必填 | 来源类型。 可选值 base64url | — |
media_type | string | 可选 | base64 图片的 MIME 类型,例如 image/png。 | — |
data | string | 可选 | Base64 编码图片数据;type=base64 时必填。 | — |
url | string | 可选 | 图片 URL;type=url 时必填且需模型支持。 | — |
idtype=tool_use 时的调用 ID。
nametype=tool_use 时的工具名称。
inputtype=tool_use 时的工具输入参数。
tool_use_idtype=tool_result 时关联的调用 ID。
contenttype=tool_result 时的工具执行结果。
is_error工具结果是否表示执行失败。
thinking思考块内容;多轮使用时按模型要求完整回传。
signature思考块签名;不得自行构造或修改。
data经隐藏处理的思考块数据;按原值回传。
cache_control内容块缓存控制;需模型支持。
messages[].content[].cache_control 的子字段 1
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
type | string | 必填 | 缓存控制类型。 可选值 ephemeral | — |
system系统提示文本,或 type=text 的文本块数组。
system[] 的子字段 3
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
type | string | 必填 | 系统内容块类型。 可选值 text | — | ||||||||||
text | string | 必填 | 系统提示文本。 | — | ||||||||||
cache_control | object | 可选 | 系统文本块缓存控制;需模型支持。 | — | ||||||||||
| ||||||||||||||
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
type | string | 必填 | 缓存控制类型。 可选值 ephemeral | — |
max_tokens本次响应允许生成的最大 Token 数,必须为正整数。
temperature采样温度,通常为 0 到 1;特定模型或思考模式可能限制使用。
top_p核采样阈值;通常不与 temperature 同时调整。
top_k仅在概率最高的 K 个候选 Token 中采样;需模型支持。
stop_sequences停止生成的自定义字符串序列。
stream设为 true 时按 SSE 事件流返回消息。
tools提供给模型的工具定义。
tools[] 的子字段 4
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 | |||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
name | string | 必填 | 工具名称。 | — | |||||||||||||||||||||||||
description | string | 可选 | 工具功能及使用场景。 | — | |||||||||||||||||||||||||
input_schema | object | 必填 | 工具输入参数的 JSON Schema。 | — | |||||||||||||||||||||||||
| |||||||||||||||||||||||||||||
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
type | string | 必填 | JSON Schema 数据类型。 | |
properties | object | 可选 | 属性名及其 JSON Schema 定义。 | — |
required | array<string> | 可选 | 必填属性名列表。 | — |
additionalProperties | boolean | 可选 | 是否允许未声明的属性;严格模式通常设为 false。 | — |
strict是否要求严格工具参数;需模型支持。
tool_choice控制模型是否以及如何调用工具。
tool_choice 的子字段 3
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
type | string | 必填 | auto=由模型选择;any=必须调用工具;tool=指定工具;none=禁用工具。 可选值 autoanytoolnone | — |
name | string | 可选 | type=tool 时必填,须对应 tools 中的名称。 | — |
disable_parallel_tool_use | boolean | 可选 | 限制单轮最多调用一个工具。 | — |
thinking扩展思考设置;仅限支持的模型。
thinking 的子字段 2
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
type | string | 必填 | 是否启用扩展思考。 可选值 enableddisabled | — |
budget_tokens | integer | 可选 | type=enabled 时的思考 Token 预算;应小于 max_tokens,并满足模型要求。 | — |
metadata请求附加元数据。
metadata 的子字段 1
| 参数名 | 类型 | 必填 | 说明 | 默认值 / 示例 |
|---|---|---|---|---|
user_id | string | 可选 | 应用内终端用户标识。 | — |
使用说明
- 请求头须包含 anthropic-version;示例使用平台 Bearer 认证。
- system 独立于 messages;messages 的角色使用 user 或 assistant。
- stream=true 时响应为 text/event-stream,包含 message_start、content_block_delta、message_delta 和 message_stop 等事件。
- 缓存命中时 usage 还可能包含 cache_creation_input_tokens、cache_read_input_tokens;下方响应为说明样例。
流式请求与 SSE 消费
先将 MODEL_ID 替换为账户可用且支持相应能力的模型,并设置环境变量 KEDANG_API_KEY。流式、工具、图像和结构化输出分别依赖模型能力。以下 Python 示例可单独保存运行,API Key 仅在服务端读取。
| 文本增量 | 成功结束 | 异常处理 |
|---|---|---|
| content_block_delta 的 text_delta | message_stop | HTTP 错误、error 事件、截断或缺少结束标记均停止处理 |
SSE 以空行分帧,多行 data: 用换行连接;不能把任意网络分块直接当作 JSON。示例读取文本增量;流式工具参数需要按调用 ID 或内容块索引累积后再解析,下面的工具示例采用非流式两步调用。
展开 Python:请求、解析事件与处理结束状态
# 安装依赖:python -m pip install requests
import base64
import json
import os
from pathlib import Path
from urllib.parse import quote
import requests
BASE_URL = "https://ai.kedang.net"
MODEL_ID = "MODEL_ID" # 替换为账户可用、支持当前能力的模型
def request_json(path, body, extra_headers=None):
headers = {"Authorization": "Bearer " + os.environ["KEDANG_API_KEY"]}
headers.update(extra_headers or {})
response = requests.post(BASE_URL + path, headers=headers, json=body, timeout=120)
response.raise_for_status()
result = response.json()
if result.get("error"):
raise RuntimeError(result["error"])
return result
def sse_lines(chunks):
"""增量解码 UTF-8,并跨网络分块正确识别 LF、CR 和 CRLF。"""
import codecs
decoder = codecs.getincrementaldecoder("utf-8")()
line, skip_lf = [], False
for chunk in chunks:
for char in decoder.decode(chunk):
if skip_lf:
skip_lf = False
if char == "\n":
continue
if char in ("\r", "\n"):
yield "".join(line)
line = []
skip_lf = char == "\r"
else:
line.append(char)
decoder.decode(b"", final=True) # 不接受 EOF 处截断的 UTF-8 字符。
if line:
yield "".join(line)
def iter_sse(lines):
"""只在空行处派发完整 SSE 帧。"""
event, data_lines = "message", []
first_line = True
for line in lines:
if first_line:
line = line.removeprefix("\ufeff")
first_line = False
if line == "":
if data_lines:
yield event, "\n".join(data_lines)
event, data_lines = "message", []
continue
if line.startswith(":"):
continue # 心跳或注释
field, separator, value = line.partition(":")
if separator and value.startswith(" "):
value = value[1:]
if field == "event":
event = value or "message"
elif field == "data":
data_lines.append(value)
# EOF 前没有空行的半帧不能当作完整事件;由下层检查终止事件。
def stream_text(events):
completed = False
for event, data in events:
if data.strip() == "[DONE]":
break
item = json.loads(data)
kind = item.get("type", event)
if kind == "error" or item.get("error"):
raise RuntimeError(item)
if kind == "content_block_delta":
delta = item.get("delta", {})
if delta.get("type") == "text_delta":
yield delta.get("text", "")
elif kind == "message_delta":
reason = item.get("delta", {}).get("stop_reason")
if reason in ("max_tokens", "refusal", "model_context_window_exceeded"):
raise RuntimeError("输出未完整完成:" + reason)
elif kind == "message_stop":
completed = True
break
# ping、思考块、签名增量不是面向用户的文本。
if not completed:
raise RuntimeError("连接在 message_stop 前结束。")
def main():
path = "/v1/messages"
body = {"model": MODEL_ID, "max_tokens": 1024, "messages": [{"role": "user", "content": "用三句话介绍杭州。"}], "stream": True}
headers = {"Authorization": "Bearer " + os.environ["KEDANG_API_KEY"],
"Accept": "text/event-stream"}
headers.update({"anthropic-version": "2023-06-01"})
with requests.post(BASE_URL + path, headers=headers, json=body,
stream=True, timeout=(10, 120)) as response:
response.raise_for_status()
if "text/event-stream" not in response.headers.get("Content-Type", ""):
raise RuntimeError("预期 SSE,请检查返回的 Content-Type 和错误信息。")
events = iter_sse(sse_lines(response.iter_content(chunk_size=128)))
for text in stream_text(events):
print(text, end="", flush=True)
print()
if __name__ == "__main__":
main()工具调用:返回结果后继续回答
第一步让模型提出工具调用,应用校验参数并执行本地函数;第二步将每个结果和原始调用上下文一起发回。示例只允许调用本地加法函数,第二轮关闭工具,避免无界循环。实际业务需自行设置允许执行的工具与轮次上限。
| 结果关联字段 | 本地工具 | 回传内容 |
|---|---|---|
| tool_result.tool_use_id | add_numbers(a, b) | JSON 对象 {"sum": 5} |
展开 Python:完整两步工具调用
# 安装依赖:python -m pip install requests
import base64
import json
import os
from pathlib import Path
from urllib.parse import quote
import requests
BASE_URL = "https://ai.kedang.net"
MODEL_ID = "MODEL_ID" # 替换为账户可用、支持当前能力的模型
def request_json(path, body, extra_headers=None):
headers = {"Authorization": "Bearer " + os.environ["KEDANG_API_KEY"]}
headers.update(extra_headers or {})
response = requests.post(BASE_URL + path, headers=headers, json=body, timeout=120)
response.raise_for_status()
result = response.json()
if result.get("error"):
raise RuntimeError(result["error"])
return result
PARAMETERS = {
"type": "object",
"properties": {"a": {"type": "number"}, "b": {"type": "number"}},
"required": ["a", "b"],
"additionalProperties": False,
}
def run_tool(name, args):
# 工具名和参数都先校验;只执行应用主动注册的函数。
if name != "add_numbers" or not isinstance(args, dict) or set(args) != {"a", "b"}:
raise ValueError("未知工具或参数不匹配")
if any(type(args[key]) not in (int, float) for key in ("a", "b")):
raise ValueError("a 和 b 必须为数字")
return {"sum": args["a"] + args["b"]}
def main():
headers = {"anthropic-version": "2023-06-01"}
tools = [{"name": "add_numbers", "description": "计算两个数字之和", "input_schema": PARAMETERS}]
messages = [{"role": "user", "content": "请用工具计算 2 加 3。"}]
first = request_json("/v1/messages", {"model": MODEL_ID, "max_tokens": 1024,
"messages": messages, "tools": tools, "tool_choice": {"type": "auto"}}, headers)
blocks = first["content"]
calls = [block for block in blocks if block.get("type") == "tool_use"]
if not calls:
print(first)
return
messages.append({"role": "assistant", "content": blocks}) # 保留完整内容块与签名。
results = []
for call in calls:
result = run_tool(call["name"], call["input"])
results.append({"type": "tool_result", "tool_use_id": call["id"],
"content": json.dumps(result, ensure_ascii=False)})
messages.append({"role": "user", "content": results})
second = request_json("/v1/messages", {"model": MODEL_ID, "max_tokens": 1024,
"messages": messages, "tools": tools, "tool_choice": {"type": "none"}}, headers)
for block in second.get("content", []):
if block.get("type") == "text":
print(block["text"])
if __name__ == "__main__":
main()图片输入
示例读取本地 input.png。文件格式与 MIME 类型必须一致;图片数量、大小和支持格式以所选模型为准。这里展示图片理解输入,生成图片请使用图像生成接口。
展开 Python:发送本地 PNG 图片
# 安装依赖:python -m pip install requests
import base64
import json
import os
from pathlib import Path
from urllib.parse import quote
import requests
BASE_URL = "https://ai.kedang.net"
MODEL_ID = "MODEL_ID" # 替换为账户可用、支持当前能力的模型
def request_json(path, body, extra_headers=None):
headers = {"Authorization": "Bearer " + os.environ["KEDANG_API_KEY"]}
headers.update(extra_headers or {})
response = requests.post(BASE_URL + path, headers=headers, json=body, timeout=120)
response.raise_for_status()
result = response.json()
if result.get("error"):
raise RuntimeError(result["error"])
return result
def main():
image = base64.b64encode(Path("input.png").read_bytes()).decode("ascii")
result = request_json("/v1/messages", {"model": MODEL_ID, "max_tokens": 1024,
"messages": [{"role": "user", "content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image}},
{"type": "text", "text": "请描述这张图片。"}
]}]}, {"anthropic-version": "2023-06-01"})
for block in result.get("content", []):
if block.get("type") == "text":
print(block["text"])
if __name__ == "__main__":
main()结构化输出
Messages 示例通过指定工具提取结构化对象;应用读取 tool_use.input 并校验,无需执行 save_trip。强制工具选择不应与不支持该组合的思考设置混用。 输出仍需处理拒绝、截断和字段类型错误。
| 当前协议字段 | 应用侧校验 |
|---|---|
| input_schema + 指定工具 | city 为字符串,days 为整数;仅接受完整返回结果 |
展开 Python:提取 JSON 对象并校验
# 安装依赖:python -m pip install requests
import base64
import json
import os
from pathlib import Path
from urllib.parse import quote
import requests
BASE_URL = "https://ai.kedang.net"
MODEL_ID = "MODEL_ID" # 替换为账户可用、支持当前能力的模型
def request_json(path, body, extra_headers=None):
headers = {"Authorization": "Bearer " + os.environ["KEDANG_API_KEY"]}
headers.update(extra_headers or {})
response = requests.post(BASE_URL + path, headers=headers, json=body, timeout=120)
response.raise_for_status()
result = response.json()
if result.get("error"):
raise RuntimeError(result["error"])
return result
SCHEMA = {
"type": "object",
"properties": {"city": {"type": "string"}, "days": {"type": "integer"}},
"required": ["city", "days"],
"additionalProperties": False,
}
def check_trip(value):
# 业务侧仍校验结果,尤其要区分拒绝、截断和有效 JSON。
if not isinstance(value, dict) or set(value) != {"city", "days"}:
raise ValueError("返回对象不匹配 Schema")
if not isinstance(value["city"], str) or type(value["days"]) is not int:
raise ValueError("字段类型不匹配 Schema")
return value
def main():
# 以命名工具承接结构化对象;结果位于 tool_use.input,而非文本字符串。
result = request_json("/v1/messages", {"model": MODEL_ID, "max_tokens": 1024,
"messages": [{"role": "user", "content": "提取旅行信息:杭州,3 天。"}],
"tools": [{"name": "save_trip", "description": "返回提取的旅行信息", "input_schema": SCHEMA}],
"tool_choice": {"type": "tool", "name": "save_trip"}},
{"anthropic-version": "2023-06-01"})
if result.get("stop_reason") != "tool_use":
raise RuntimeError("未得到完整工具输入")
calls = [block for block in result["content"]
if block.get("type") == "tool_use" and block.get("name") == "save_trip"]
if len(calls) != 1:
raise RuntimeError("预期一个 save_trip 结构化结果")
print(check_trip(calls[0]["input"]))
if __name__ == "__main__":
main()