EasyXAI 文档
API 接入

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
}

注意:

  1. Auto 模式:模型可以自行决定是否使用工具
  2. Any 模式:模型必须使用工具,但可以选择任何可用的工具
  3. 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 anthropic
from 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/sdk
import 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);
}

Anthropic Messages reference

Streaming reference