Anthropic 协议
POST https://api.easyx.ai/v1/messages
x-api-key: easyx_ws_xxx
anthropic-version: 2023-06-01
Content-Type: application/json请求示例
基础文本对话
curl https://api.easyx.ai/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: easyx_ws_xxx" \
--data \
'{
"model": "claude-sonnet-4.5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Hello, world"
}
]
}'响应示例:
{
"content": [
{
"text": "Hi! My name is Claude.",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-sonnet-4.5",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2095,
"output_tokens": 503
}
}图像分析对话
curl https://api.easyx.ai/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: easyx_ws_xxx" \
--data \
'{
"model": "claude-sonnet-4.5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
},
{
"type": "text",
"text": "这张图片里有什么?"
}
]
}
],
"max_tokens": 1024
}'响应示例:
{
"content": [
{
"text": "这张图片显示了一只橙色的猫咪正在窗台上晒太阳。猫咪看起来很放松,眯着眼睛享受阳光。窗外可以看到一些绿色的植物。",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-sonnet-4.5",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 3050,
"output_tokens": 892
}
}工具调用
curl https://api.easyx.ai/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: easyx_ws_xxx" \
--data \
'{
"model": "claude-sonnet-4.5",
"messages": [
{
"role": "user",
"content": "今天北京的天气怎么样?"
}
],
"tools": [
{
"name": "get_weather",
"description": "获取指定位置的当前天气",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称,如:北京"
}
},
"required": [
"location"
]
}
}
],
"max_tokens": 1024
}'响应示例:
{
"content": [
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": {
"location": "北京"
}
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-sonnet-4.5",
"role": "assistant",
"stop_reason": "tool_use",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2156,
"output_tokens": 468
}
}系统提示与多轮对话
系统提示放在顶层 system 中。messages 的角色为 user 和 assistant,多轮调用时一起发送历史消息。
curl https://api.easyx.ai/v1/messages \
-H "x-api-key: easyx_ws_xxx" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4.5",
"max_tokens": 1024,
"system": "请用中文回答。",
"messages": [
{
"role": "user",
"content": "我叫小明。"
},
{
"role": "assistant",
"content": "你好,小明。"
},
{
"role": "user",
"content": "我叫什么名字?"
}
]
}'流式响应
curl -N https://api.easyx.ai/v1/messages \
-H "x-api-key: easyx_ws_xxx" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4.5",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "Hello"
}
],
"stream": true
}'event: message_start
data: {"type":"message_start","message":{"id":"msg_example","type":"message","role":"assistant","content":[],"stop_reason":null,"usage":{"input_tokens":10,"output_tokens":0}}}
event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}}
event: content_block_stop
data: {"type":"content_block_stop","index":0}
event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":1}}
event: message_stop
data: {"type":"message_stop"}按 index 拼接 content_block_delta。文本使用 text_delta,工具参数使用 input_json_delta;还需处理 ping 和 error 事件。
回传工具结果
保留助手返回的 tool_use 内容,再追加包含 tool_result 的 user 消息。tool_use_id 必须对应返回的工具调用 id,继续调用时保留 tools 定义。
curl https://api.easyx.ai/v1/messages \
-H "x-api-key: easyx_ws_xxx" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "claude-sonnet-4.5",
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "查询天气",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string"
}
},
"required": [
"location"
]
}
}
],
"messages": [
{
"role": "user",
"content": "北京的天气怎么样?"
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_weather",
"name": "get_weather",
"input": {
"location": "北京"
}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_weather",
"content": "22°C,晴"
}
]
}
]
}'参数
请求头参数
anthropic-beta
- 类型:字符串
- 必需:否
指定要使用的 beta 版本,支持用逗号分隔的列表如 beta1,beta2,或多次指定该请求头。
anthropic-version
- 类型:字符串
- 必需:是
指定要使用的 API 版本。
请求体参数
max_tokens
- 类型:整数
- 必需:是
生成的最大 token 数量。不同模型有不同的限制,详见模型文档。
messages
- 类型:对象数组
- 必需:是
输入消息列表。模型被训练为在用户和助手之间交替进行对话。创建新消息时,您可以使用 messages 参数指定之前的对话轮次,模型将生成对话中的下一条消息。连续的用户或助手消息会被合并为单个轮次。
每个消息必须包含 role 和 content 字段。您可以指定单个用户角色消息,或包含多个用户和助手消息。
单条用户消息示例:
[
{
"role": "user",
"content": "Hello, Claude"
}
]多轮对话示例:
[
{
"role": "user",
"content": "你好。"
},
{
"role": "assistant",
"content": "你好!我是 Claude。有什么可以帮你的吗?"
},
{
"role": "user",
"content": "请用简单的话解释什么是 LLM?"
}
]{
"role": "user",
"content": [
{
"type": "text",
"text": "Hello, Claude"
}
]
}从 Claude 3 模型开始,您还可以发送图片内容块:
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
},
{
"type": "text",
"text": "这张图片里有什么?"
}
]
}目前支持的图片格式包括: base64, image/jpeg、image/png、image/gif 和 image/webp。
messages.role
- 类型:枚举字符串
- 必需:是
- 可选值:user, assistant
注意:Messages API 中没有 "system" 角色,如果需要系统提示,请使用顶层的 system 参数。
messages.content
- 类型:字符串或对象数组
- 必需:是
消息内容可以是以下几种类型之一:
文本内容 (Text)
{
"type": "text",
"text": "Hello, Claude",
"cache_control": {
"type": "ephemeral"
}
}图片内容 (Image)
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
},
"cache_control": {
"type": "ephemeral"
}
}工具使用 (Tool Use)
{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": {},
"cache_control": {
"type": "ephemeral"
}
}工具结果 (Tool Result)
{
"type": "tool_result",
"tool_use_id": "toolu_xyz...",
"content": "结果内容",
"is_error": false,
"cache_control": {
"type": "ephemeral"
}
}当 content 为内容块数组时,每个内容块可以是文本或图片:
{
"type": "tool_result",
"tool_use_id": "toolu_xyz...",
"content": [
{
"type": "text",
"text": "分析结果",
"cache_control": {
"type": "ephemeral"
}
},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "..."
},
"cache_control": {
"type": "ephemeral"
}
}
]
}model
- 类型:字符串
- 必需:是
要使用的模型名称,详见模型文档。范围 1 - 256 个字符。
metadata
- 类型:对象
- 必需:否
描述请求元数据的对象。包含以下可选字段:
user_id: 与请求关联的用户的外部标识符。应该是 uuid、哈希值或其他不透明标识符。不要包含任何标识信息如姓名、邮箱或电话号码。最大长度:256。
stop_sequences
- 类型:字符串数组
- 必需:否
自定义的停止生成的文本序列。
stream
- 类型:布尔值
- 必需:否
是否使用服务器发送事件 (SSE) 来增量返回响应内容。
system
- 类型:字符串
- 必需:否
系统 prompt,为 Claude 提供背景和指令。这是一种为模型提供上下文和特定目标或角色的方式。注意这与消息中的 role 不同,Messages API 中没有 "system" 角色。
temperature
- 类型:数字
- 必需:否
- 默认值:1.0
控制生成随机性,0.0 - 1.0。建议对于分析性/选择题类任务使用接近 0.0 的值,对于创造性和生成性任务使用接近 1.0 的值。
注意:即使 temperature 设置为 0.0,结果也不会完全确定。
tool_choice
- 类型:对象
- 必需:否
控制模型如何使用提供的工具。可以是以下三种类型之一:
1. Auto 模式 (自动选择)
{
"type": "auto",
"disable_parallel_tool_use": false
}2. Any 模式 (任意工具)
{
"type": "any",
"disable_parallel_tool_use": false
}3. Tool 模式 (指定工具)
{
"type": "tool",
"name": "get_weather",
"disable_parallel_tool_use": false
}注意:
- Auto 模式:模型可以自行决定是否使用工具
- Any 模式:模型必须使用工具,但可以选择任何可用的工具
- Tool 模式:模型必须使用指定的工具
tools
- 类型:对象数组
- 必需:否
定义模型可能使用的工具。工具可以是自定义工具或内置工具类型:
1. 自定义工具(Tool)
每个自定义工具定义包含:
type: 可选,枚举值: "custom"name: 工具名称,必需,1-64 个字符description: 工具描述,建议尽可能详细input_schema: 工具输入的 JSON Schema 定义,必需cache_control: 缓存控制,可选,type为 "ephemeral"
示例:
[
{
"name": "get_weather",
"description": "获取指定位置的当前天气",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称,如:北京"
}
},
"required": [
"location"
]
}
}
]top_k
- 类型:整数
- 必需:否
- 范围:x > 0
从 token 的前 K 个选项中采样。用于移除低概率的"长尾"响应。建议仅在高级用例中使用,通常只需要调整 temperature。
top_p
- 类型:数字
- 必需:否
- 范围:0 ≤ x ≤ 1
使用 nucleus 采样。计算每个后续 token 按概率降序排列的累积分布,在达到 top_p 指定的概率时截断。建议仅调整 temperature 或 top_p 其中之一,不要同时使用。
思考与提示缓存
支持手动思考预算的模型可使用 thinking.type=enabled,并设置小于 max_tokens 的 budget_tokens;支持自适应思考的模型使用对应的 thinking 配置。回传历史时保留模型返回的 thinking 块与 signature。提示缓存可在支持的内容块中设置 cache_control。
{
"system": [
{
"type": "text",
"text": "这里放需要复用的长指令。",
"cache_control": {
"type": "ephemeral"
}
}
],
"thinking": {
"type": "enabled",
"budget_tokens": 2048
},
"max_tokens": 4096
}响应字段
成功响应
返回一个聊天补全对象,包含以下字段:
content
- 类型:对象数组
- 必需:是
模型生成的内容,由多个内容块组成。每个内容块都有一个确定其形状的 type。内容块可以是以下类型之一:
文本内容块 (Text)
{
"type": "text",
"text": "你好,我是 Claude。"
}工具使用内容块 (Tool Use)
{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": {}
}示例: 文本内容示例
[
{
"type": "text",
"text": "你好,我是 Claude。"
}
]工具使用示例
[
{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": {
"location": "北京"
}
}
]混合内容示例
[
{
"type": "text",
"text": "根据天气查询结果:"
},
{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": {
"location": "北京"
}
}
]id
- 类型:字符串
- 必需:是
响应的唯一标识符。
model
- 类型:字符串
- 必需:是
使用的模型名称。
role
- 类型:枚举字符串
- 必需:是
- 默认值:assistant
生成消息的会话角色,始终为 "assistant"。
stop_reason
- 类型:枚举字符串或 null
- 必需:是
停止生成的原因,可能的值包括:
"end_turn": 模型达到自然停止点"max_tokens": 超过请求的max_tokens或模型的最大限制"stop_sequence": 生成了自定义停止序列之一"tool_use": 模型调用了一个或多个工具
在非流式模式下,此值始终非空。在流式模式下,在 message_start 事件中为 null,message_delta 事件中提供最终原因。
stop_sequence
- 类型:字符串或 null
- 必需:是
生成的自定义停止序列。如果模型遇到了 stop_sequences 参数中指定的某个序列,这个字段将包含该匹配的停止序列。如果不是因为停止序列而停止,则为 null。
type
- 类型:枚举字符串
- 必需:是
- 默认值:message
- 可选值:message
对象类型,对于 Messages 始终为 "message"。
usage
- 类型:对象
- 必需:是
计费和限流相关的使用量统计。包含以下字段:
input_tokens: 使用的输入 token 数量,可按实际用量返回output_tokens: 使用的输出 token 数量,可按实际用量返回cache_creation_input_tokens: 创建缓存条目使用的输入 token 数量(如果适用),可按实际用量返回cache_read_input_tokens: 从缓存读取的输入 token 数量(如果适用),可按实际用量返回
注意:由于 API 在内部会对请求进行转换和解析,token 计数可能与请求和响应的实际可见内容不完全对应。例如,即使是空字符串响应,output_tokens 也会是非零值。
Python SDK
pip install anthropicfrom anthropic import Anthropic
client = Anthropic(api_key="easyx_ws_xxx", base_url="https://api.easyx.ai")
message = client.messages.create(
model="claude-sonnet-4.5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
)
for block in message.content:
if block.type == "text":
print(block.text)
with client.messages.stream(
model="claude-sonnet-4.5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello"}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)Node.js SDK
npm install @anthropic-ai/sdkimport Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({
apiKey: "easyx_ws_xxx",
baseURL: "https://api.easyx.ai",
});
const message = await client.messages.create({
model: "claude-sonnet-4.5",
max_tokens: 1024,
messages: [{ role: "user", content: "Hello" }],
});
for (const block of message.content) {
if (block.type === "text") console.log(block.text);
}