Anthropic 对话格式(Messages)
Anthropic 对话格式(Messages)
📝 简介
💡 请求示例
基础文本对话 ✅
{
"content": [
{
"text": "Hi! My name is Claude.",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2095,
"output_tokens": 503
}
}
图像分析对话 ✅
{
"content": [
{
"text": "这张图片显示了一只橙色的猫咪正在窗台上晒太阳。猫咪看起来很放松,眯着眼睛享受阳光。窗外可以看到一些绿色的植物。",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 3050,
"output_tokens": 892
}
}
工具调用 ✅
{
"content": [
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": { "location": "北京" }
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"stop_reason": "tool_use",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2156,
"output_tokens": 468
}
}
流式响应 ✅
{
"type": "message_start",
"message": {
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-3-5-sonnet-20241022",
"role": "assistant",
"type": "message"
}
}
{
"type": "content_block_start",
"index": 0,
"content_block": {
"type": "text"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "从前"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "有一只"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "小兔子..."
}
}
{
"type": "content_block_stop",
"index": 0
}
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"usage": {
"input_tokens": 2045,
"output_tokens": 628
}
}
}
{
"type": "message_stop"
}
📮 请求
端点
POST /v1/messages
鉴权方法
x-api-key: $NEWAPI_API_KEY
$NEWAPI_API_KEY
是您的 API 密钥。您可以通过控制台获取 API 密钥,每个密钥仅限于一个工作区使用。请求头参数
anthropic-beta
beta1,beta2
,或多次指定该请求头。anthropic-version
请求体参数
max_tokens
x > 1
。messages
role
和 content
字段。您可以指定单个用户角色消息,或包含多个用户和助手消息。如果最后一条消息使用助手角 色,响应内容将直接从该消息的内容继续,这可以用来约束模型的响应。[{"role": "user", "content": "Hello, Claude"}]
[
{"role": "user", "content": "你好。"},
{"role": "assistant", "content": "你好!我是 Claude。有什么可以帮你的吗?"},
{"role": "user", "content": "请用简单的话解释什么是 LLM?"}
]
[
{"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "正确答案是 ("}
]
{"role": "user", "content": "Hello, Claude"}
{
"role": "user",
"content": [{"type": "text", "text": "Hello, Claude"}]
}
{
"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
messages.content
文本内容 (Text)
{
"type": "text", // 必需,枚举值: "text"
"text": "Hello, Claude", // 必需,最小长度: 1
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}
图片内容 (Image)
{
"type": "image", // 必需,枚举值: "image"
"source": { // 必需
"type": "base64", // 必需,枚举值: "base64"
"media_type": "image/jpeg", // 必需,支持: image/jpeg, image/png, image/gif, image/webp
"data": "/9j/4AAQSkZJRg..." // 必需,base64 编码的图片数据
},
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}
工具使用 (Tool Use)
{
"type": "tool_use", // 必需,枚举值: "tool_use",默认值
"id": "toolu_xyz...", // 必需,工具使用的唯一标识符
"name": "get_weather", // 必需,工具名称,最小长度: 1
"input": { // 必需,工具的输入参数对象
// 工具输入参数,具体格式由工具的 input_schema 定义
},
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}
工具结果 (Tool Result)
{
"type": "tool_result", // 必需,枚举值: "tool_result"
"tool_use_id": "toolu_xyz...", // 必需
"content": "结果内容", // 必需,可以是字符串或内容块数组
"is_error": false, // 可选,布尔值
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}
{
"type": "tool_result",
"tool_use_id": "toolu_xyz...",
"content": [
{
"type": "text", // 必需,枚举值: "text"
"text": "分析结果", // 必需,最小长度: 1
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
},
{
"type": "image", // 必需,枚举值: "image"
"source": { // 必需
"type": "base64", // 必需,枚举值: "base64"
"media_type": "image/jpeg",
"data": "..."
},
"cache_control": {
"type": "ephemeral"
}
}
]
}
文档 (Document)
{
"type": "document", // 必需,枚举值: "document"
"source": { // 必需
// 文档源数据
},
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}
1.
cache_control
字段,用于控制内容的缓存行为2.
3.
4.
model
1 - 256
个字符。metadata
user_id
: 与请求关联的用户的外部标识符。应该是 uuid、哈希值或其他不透明标识符。不要包含任何标识信息如姓名、邮箱或电话号码。最大长度:256。stop_sequences
stream
system
temperature
0 < x < 1
。建议对于分析性/选择题类任务使用接近 0.0 的值,对于创造性和生成性任务使用接近 1.0 的值。🆕 thinking
1. 启用模式
{
"type": "enabled",
"budget_tokens": 2048
}
type
: 必需,枚举值: "enabled"budget_tokens
: 必需,整数。决定 Claude 可以用于内部推理过程的 token 数量。更大的预算可以让模型对复杂问题进行更深入的分析,提高响应质量。必须 ≥1024 且小于 max_tokens。范围 x > 1024
。2. 禁用模式
{
"type": "disabled"
}
type
: 必需,枚举值: "disabled"tool_choice
1. Auto 模式 (自动选择)
{
"type": "auto", // 必需,枚举 值: "auto"
"disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型最多只会使用一个工具
}
2. Any 模式 (任意工具)
{
"type": "any", // 必需,枚举值: "any"
"disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型将恰好使用一个工具
}
3. Tool 模式 (指定工具)
{
"type": "tool", // 必需,枚举值: "tool"
"name": "get_weather", // 必需,指定要使用的工具名称
"disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型将恰好使用一个工具
}
1.
2.
3.
tools
1. 自定义工具(Tool)
type
: 可选,枚举值: "custom"name
: 工具名称,必需,1-64 个字符description
: 工具描述,建议尽可能详细input_schema
: 工具输入的 JSON Schema 定义,必需cache_control
: 缓存控制,可选,type 为 "ephemeral"[
{
"type": "custom",
"name": "get_weather",
"description": "获取指定位置的当前天气",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "城市名称,如:北京"
}
},
"required": ["location"]
}
}
]
2. 计算机工具 (ComputerUseTool)
{
"type": "computer_20241022", // 必需
"name": "computer", // 必需,枚举值: "computer"
"display_width_px": 1024, // 必需,显示宽度(像素)
"display_height_px": 768, // 必需,显示高度(像素)
"display_number": 0, // 可选,X11 显示编号
"cache_control": {
"type": "ephemeral" // 可选
}
}
3. Bash 工具 (BashTool)
{
"type": "bash_20241022", // 必需
"name": "bash", // 必需,枚举值: "bash"
"cache_control": {
"type": "ephemeral" // 可选
}
}
4. 文本编辑器工具 (TextEditor)
{
"type": "text_editor_20241022", // 必需
"name": "str_replace_editor", // 必需,枚举值: "str_replace_editor"
"cache_control": {
"type": "ephemeral" // 可选
}
}
[
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": { "location": "北京" }
}
]
[
{
"type": "tool_result",
"tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"content": "北京当前天气晴朗,温度 25°C"
}
]
top_k
top_p
📥 响应
成功响应
content
文本内容块 (Text)
{
"type": "text", // 必需,枚举值: "text",默认值
"text": "你好,我是 Claude。" // 必需,最大长度: 5000000,最小长度: 1
}
工具使用内容块 (Tool Use)
{
"type": "tool_use", // 必需,枚举值: "tool_use",默认值
"id": "toolu_xyz...", // 必需,工具使用的唯一标识符
"name": "get_weather", // 必需,工具名称,最小长度: 1
"input": { // 必需,工具的输入参数对象
// 工具输入参数,具体格式由工具的 input_schema 定义
}
}
// 文本内容示例
[{"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": "北京" }
}
]
// 请求
[
{"role": "user", "content": "太阳的希腊语名字是什么? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "正确答案是 ("}
]
// 响应
[{"type": "text", "text": "B)"}]
id
model
role
stop_reason
"end_turn"
: 模型达到自然停止点"max_tokens"
: 超过请求的 max_tokens 或模型的最大限制"stop_sequence"
: 生成了自定义停止序列之一"tool_use"
: 模型调用了一个或多个工具stop_sequence
type
usage
input_tokens
: 使用的输入 token 数量,必需,范围 x > 0output_tokens
: 使用的输出 token 数量,必需,范围 x > 0cache_creation_input_tokens
: 创建缓存条目使用的输入 token 数量(如果适用),必需,范围 x > 0cache_read_input_tokens
: 从缓存读取的输入 token 数量(如果适用),必需,范围 x > 0错误响应
常见错误状态码
401 Unauthorized
: API 密钥无效或未提供400 Bad Request
: 请求参数无效429 Too Many Requests
: 超出 API 调用限制500 Internal Server Error
: 服务器内部错误{
"error": {
"type": "invalid_request_error",
"message": "Invalid API key provided",
"code": "invalid_api_key"
}
}
invalid_request_error
: 请求参数错误authentication_error
: 认证相关错误rate_limit_error
: 请求频率超限server_error
: 服务器内部错误修改于 2025-05-30 01:34:51