帮你快速理解、总结文档立即下载

Anthropic Message 协议字段说明

最近更新时间:2026-08-12 08:55:05
我的收藏

Anthropic Messages API 使用

请求参数详解

基础参数

参数
类型
必选
说明
model
string
要使用的模型名称,如 deepseek-v4-flash。也支持 Claude 系列及其他 Anthropic 兼容模型名。需要图像输入时,请选择支持视觉能力的模型(如 qwen3.5-flashqwen3.5-plus);deepseek-v4-flashhy3 为纯文本模型,传入图像不会报错但不会被识别。
messages
array
对话消息列表,按时间顺序排列,含完整上下文。平台不做会话管理,多轮对话需由客户端完整携带历史。详情请参见 Message 对象详解
system
string 或 array
系统提示词。不在 messages 内,通过顶层 system 字段单独传入。这是与 OpenAI Chat 协议的关键区别。
max_tokens
integer
模型单次输出的最大 Token 数上限。不同模型有各自上限;思维链消耗的 Token 计入此限制,因此开启 thinking 时须大于 budget_tokens。达到上限时 stop_reason"max_tokens"
stream
boolean
是否启用流式响应(默认 false)。true 时以 SSE 格式逐事件返回。
system 支持两种形式:
// 字符串
"system": "你是一个友好的助手"

// 内容块数组(可携带 cache_control)
"system": [
{ "type": "text", "text": "你是一个友好的助手" },
{ "type": "text", "text": "<长文档>", "cache_control": { "type": "ephemeral" } }
]
说明:
关于 max_tokens:Anthropic 协议中该字段为必填。部分模型对缺失或非法 max_tokens 会做宽松兜底处理,但请始终按协议标准显式传入该字段,不要依赖兜底行为。

生成控制参数

参数
类型
范围
说明
temperature
float
[0, 1]
采样温度。注意 Anthropic 范围为 [0, 1],与 OpenAI 的 [0, 2] 不同。
top_p
float
(0, 1]
核采样。一般 temperaturetop_p 只调其中一个。
top_k
integer
-
只从概率最高的前 K 个 token 中采样。Anthropic 特有参数,OpenAI Chat 协议无此字段。
stop_sequences
string[]
-
自定义停止序列。命中任一序列时立即停止,stop_reason"stop_sequence",命中的序列回写在响应的 stop_sequence 字段。
说明:
关于 thinking 与 temperature:开启 thinking 时,部分模型要求 temperature 固定为 1;也有模型会容忍 temperature != 1。建议 thinking 场景使用默认值或 1,是否强校验按模型而定。 关于 stop_sequences:部分模型能稳定回写 stop_reason=stop_sequence 与命中的 stop_sequence,部分模型不保证回写。依赖精确停止语义的业务应针对目标模型验证。

工具调用

Anthropic 的工具定义结构与 OpenAI 不同:字段直接平铺,参数字段名为 input_schema(OpenAI 为 function.parameters)。
{
"name": "get_weather",
"description": "查询指定城市的天气信息",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string", "description": "城市名称" }
},
"required": ["location"]
}
}
字段
类型
必填
说明
name
string
工具名称。
description
string
工具用途描述,帮助模型判断何时调用。
input_schema
object
参数定义,遵循 JSON Schema 格式。
type
string
普通工具留空;内置工具填类型名(如 web_search_20250305)。
max_uses
integer
内置工具单次会话最大调用次数。
cache_control
object
工具定义级缓存标记。
tool_choice(Anthropic 用对象形式):
Anthropic tool_choice
等价 OpenAI
说明
{"type":"auto"}
"auto"
默认,模型自行决定
{"type":"any"}
"required"
强制调用任一工具
{"type":"none"}
"none"
禁止调用工具
{"type":"tool","name":"x"}
{"type":"function","function":{"name":"x"}}
强制调用指定工具
可选子字段 disable_parallel_tool_use(boolean):设为 true 时禁止单次响应并行调用多个工具。
注意:
与 thinking 的组合限制:开启或默认进入 thinking 模式时,部分模型不支持强制工具调用(tool_choice:anytool_choice:tool),通常仅支持 auto / none 与 thinking 共用。如需强制工具调用,建议先显式传 thinking: {"type":"disabled"} 再使用 any 或指定工具。各模型的具体差异见 各模型字段兼容情况

思维链(Extended Thinking)

启用扩展思维链,让模型在生成最终回复前先进行内部推理,适用于复杂逻辑、数学、代码等任务。
{
"thinking": {
"type": "enabled",
"budget_tokens": 8000
}
}
字段
类型
必填
说明
type
string
"enabled" 开启 / "disabled" 关闭 / "adaptive" 自适应。
budget_tokens
integer
视情况
enabled 时建议提供,思维链 token 预算(建议 1024~32000),须小于 max_tokens
display
string
思维过程展示方式(部分模型支持)。
不同 type 的字段要求enabled 携带 budget_tokens(及可选 display);disabledtypeadaptive 携带 type(及可选 display),由模型自适应分配预算。
说明:
模型差异:部分推理模型在不传 thinking 时也会默认返回 thinking block;部分模型会容忍缺失 budget_tokensbudget_tokens >= max_tokenstemperature != 1 等非严格约束。这类属于模型/平台兼容行为,不应当作所有模型的通用契约。如不希望返回思考内容,建议显式传 thinking: {"type":"disabled"}与 OpenAI 兼容参数的关系:部分厂商文档会使用 enable_thinkingreasoning_effort 等字段描述思考能力。在 Anthropic Messages 协议中,对应表达为 thinking.typeoutput_config.effort,以及多轮历史中原样回传 assistant 的 thinking / redacted_thinking 内容块;不要在 Messages 请求体中直接混用 enable_thinking
交错思维链(Interleaved Thinking):部分模型支持在生成回复过程中穿插思维内容。混元等模型通过请求头 Hunyuan-Beta 开启,平台会将该头透传给模型服务。该请求头属扩展能力,不支持的模型会忽略该头而不报错;是否实际生效需结合所用模型的能力说明确认。

输出配置

output_config(object):控制输出努力程度与结构化格式。
{
"output_config": {
"effort": "high",
"format": {
"type": "json_schema",
"schema": { "type": "object", "properties": { "answer": { "type": "string" } } }
}
}
}
字段
类型
说明
effort
string
输出努力程度:low / medium / high / xhigh / max
format.type
string
结构化输出类型(如 json_schema)。
format.schema
object
JSON Schema 定义。
说明:
该字段为扩展能力,各厂商支持情况不一:output_config.effort 多数模型可接收;output_config.format.type=json_schema 的结构化输出仅部分模型能稳定按 schema 生成 JSON,部分模型返回 200 但 JSON 不完全符合 schema,也有模型返回 400。不要将 json_schema 当作所有模型的通用能力,使用前请针对目标模型验证。

缓存(Prompt Caching)

通过 cache_control 标记可缓存内容,命中后大幅降低重复 prompt 的 input_tokens 计费。支持三个层级标记:
层级
标记位置
说明
工具级
tools[n].cache_control
缓存工具定义
系统级
system[n].cache_control
缓存 system 内容块
消息/内容块级
messages[n].content[m].cache_control
缓存历史消息或内容块
cache_control 对象结构:
{ "type": "ephemeral" } // 默认 5 分钟 TTL
{ "type": "ephemeral", "ttl": "1h" } // 1 小时 TTL
缓存命中情况通过响应 usage 中的 cache_creation_input_tokenscache_read_input_tokens 返回。若模型不支持缓存,相关 token 统计为 0。
说明:
能力说明:多数模型可观察到部分 cache token,但顶层 cache_control、文档块级 cache、ttl:"1h" 明细、cache_creation.ephemeral_1h_input_tokens 等普遍不完整。建议按“部分支持 Prompt Caching” 理解,不要依赖完整的 Anthropic TTL / usage 明细。

元信息与服务层级

metadata(object):请求元信息,metadata.user_id(string)为终端用户唯一标识,用于滥用检测、用量归因。
service_tier(string):服务层级 / TPM 保障渠道标识,响应中会回写实际命中的层级。
取值
说明
auto
自动选择
standard
标准层级
priority
优先层级(更高保障)
batch
批处理层级

请求头

请求头
必填
说明
x-api-key
API Key(Anthropic 官方习惯);平台同时兼容 Authorization: Bearer <key>
anthropic-version
API 版本,固定 2023-06-01
content-type
application/json
anthropic-beta
beta 功能开关(如 prompt-cachinginterleaved-thinking 等),平台原样透传给模型服务。

Message 对象详解

messages 数组中的每个元素代表对话中的一条消息。
role 枚举:
role
含义
使用位置
user
人类用户的输入(含工具结果 tool_result)
奇数轮对话。
assistant
模型的历史回复(可含 text / thinking / tool_use)
偶数轮对话,多轮时需携带历史。
说明:
关键差异:Anthropic 协议没有独立的 tool role。工具执行结果以 user 消息中的 tool_result 内容块表达,且紧跟在对应 assistanttool_use 之后。这与 OpenAI Chat 协议(独立 tool role)不同。system 不在 messages 内,通过顶层 system 字段传入。
content 格式:支持字符串与内容块数组两种形式。
// 字符串
{ "role": "user", "content": "你好" }

// 内容块数组
{
"role": "user",
"content": [
{ "type": "text", "text": "这张图片里有什么?" },
{ "type": "image", "source": { "type": "url", "url": "https://example.com/img.jpg" } }
]
}
content block 类型:
block type
关键字段
适用 role
说明
text
textcache_control
user / assistant
文本内容
image
source
user
图片
video
source
user
视频
document
sourcetitlecontextcitationscache_control
user
文档输入与引用
search_result
sourcetitlecontentcitations
user
搜索结果内容块
tool_use
idnameinput
assistant
模型请求调用工具
tool_result
tool_use_idcontent
user
工具执行结果
thinking
thinkingsignature
assistant
思维链内容
redacted_thinking
data
assistant
加密思维链
说明:
能力说明texttool_use、文本 tool_resultthinking 在支持相应能力的模型上整体可用。image block 需使用明确支持视觉/多模态的模型;纯文本模型会返回 400。document 多数模型可接收但不返回 citations;search_result 当前模型普遍不支持。
多模态 block:
图片块(type: "image"):
// Base64
{ "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQ..." } }

// URL
{ "type": "image", "source": { "type": "url", "url": "https://example.com/photo.jpg" } }
source 字段
类型
说明
type
string
"base64""url"
media_type
string
base64 时必填,如 image/jpegimage/pngimage/gifimage/webp
data
string
base64 时的图片数据。
url
string
url 时的图片地址。
detail
string
low / high / auto,图像分析精度。
说明:
能力说明:需要图片理解时应使用明确支持视觉/多模态(VL)的模型,并在模型能力说明中单独确认;纯文本模型对 image block 返回 400。
文档块(type: "document"):source(支持文本、base64、URL 等)、titlecontextcitationscache_control。多数模型可接收文档请求(返回 200),但响应不包含 citations,适合作为普通上下文降级处理,不应承诺 Anthropic 引用能力。
搜索结果块(type: "search_result"):用于把外部搜索结果作为带来源的内容块交给模型,通常配合 citations 使用。当前模型普遍返回 400,不支持该 content block。
视频块(type: "video"):结构与图片块一致,source 额外支持 fps(采样帧率)字段。视频理解为各厂商扩展能力,并非 Anthropic 官方原生支持。
工具相关 block:
tool_use(assistant 消息)——模型请求调用工具时携带:
{ "type": "tool_use", "id": "toolu_001", "name": "get_weather", "input": { "location": "北京" } }
字段
类型
说明
id
string
工具调用唯一 ID,需在对应 tool_result 中回传。
name
string
调用的工具名称。
input
object
工具参数(对象,非 JSON 字符串,与 OpenAI 的 arguments 字符串不同)。
tool_result(user 消息)——工具执行后,结果以 tool_result 块放入 user 消息:
{ "type": "tool_result", "tool_use_id": "toolu_001", "content": "北京今天晴天,25度" }
字段
类型
说明
tool_use_id
string
对应 tool_use.id
content
string 或 array
工具结果,可为纯文本或内容块数组(支持文本+图片)。
is_error
boolean
工具执行失败时设为 true
cache_control
object
缓存标记。
注意:
排列要求:同一 assistant 轮次产生的所有 tool_result,必须放在同一条紧随其后的 user 消息中。图片类型的 tool_result.content 仅部分多模态模型支持。
思维链相关 block:
thinking(assistant 消息):
{ "type": "thinking", "thinking": "让我逐步分析:外层 n 次,内层 log n 次...", "signature": "EqoBCkgIARgC..." }
字段
类型
说明
thinking
string
模型的推理过程文本
signature
string
思维块完整性签名
注意:
多轮回传要求:多轮对话时,assistant 历史消息中的 thinking 块必须原样携带 signature 回传,否则服务返回 400 Invalid signaturesignature 是加密凭证,不能截断或修改。该校验语义主要适用于 Claude 系列模型;其他模型以自有协议承载思维链时,回传要求以对应模型的说明为准。部分模型(如 deepseek-v4-flashhy3)不返回 signature,此时多轮对话无需回传该字段。
redacted_thinking(assistant 消息):部分思维内容因安全原因被加密,以 { "type": "redacted_thinking", "data": "<加密数据>" } 返回,仅含 data 字段。多轮对话时需按原顺序全部回传,以维持上下文续写能力。该内容块主要出现在 Claude 系列模型,其他模型通常不返回。

响应参数详解

非流式响应

{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"model": "<your-model-name>",
"content": [
{ "type": "thinking", "thinking": "...", "signature": "..." },
{ "type": "text", "text": "回复内容" },
{ "type": "tool_use", "id": "toolu_xxx", "name": "get_weather", "input": { "location": "北京" } }
],
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
},
"service_tier": "standard"
}
字段
类型
说明
id
string
响应唯一标识(msg_ 前缀)。
type
string
固定 "message"
role
string
固定 "assistant"
model
string
实际使用的模型名称。
content
array
内容块数组,顺序通常为 thinking → text → tool_use
stop_reason
string
停止原因,见下方枚举。
stop_sequence
string 或 null
命中的停止序列(命中 stop_sequences 时)。
usage
object
Token 用量,请参见 Token 用量
container
object
代码执行容器信息(idexpires_at),仅用到 code_execution 内置工具时返回。
service_tier
string
实际命中的服务层级。
说明:
请求追踪 ID:排查日志时优先使用响应体 id;流式响应优先使用 message_start 事件的 data.message.id。平台会同时透传/生成客户端请求头中的 X-Request-Id / X-Tc-Requestid,但最终有效的模型响应 ID 以 message id 为准。

流式响应(SSE)

stream: true 时返回 SSE,响应头 Content-Type: text/event-streamCache-Control: no-cacheConnection: keep-alive
标准事件顺序:
message_start
→ content_block_start → content_block_delta(多次) → content_block_stop (第 1 个块)
→ content_block_start → content_block_delta(多次) → content_block_stop (第 2 个块)
...
→ message_delta → message_stop
辅助事件:ping(保活心跳)、error(错误)。每个 SSE 帧格式为 event: <类型> + data: {json}
主要事件说明:
事件
含义
关键字段
message_start
消息开始,返回初始 message 骨架
message(含初始 usage 的 input/cache)
content_block_start
一个内容块开始
indexcontent_block(type 为 text/thinking/tool_use)
content_block_delta
内容增量
indexdelta(见下表)
content_block_stop
一个内容块结束
index
message_delta
消息级增量
delta.stop_reasonusage(最终 output_tokens)
message_stop
消息结束
-
content_block_delta.delta 类型:
delta.type
字段
含义
text_delta
text
文本增量。
thinking_delta
thinking
思维过程增量。
signature_delta
signature
思维块完整性签名(在 thinking 块结束前下发)。
input_json_delta
partial_json
工具参数 JSON 片段,需累积后整体解析。
说明:
流式错误处理:若在发送响应头(HTTP 200)之前发生错误,返回标准 JSON 错误体或触发故障转移重试;若流已开始后发生错误,以 error 事件下发或直接关闭连接,客户端需通过连接异常感知。 能力说明:基础 SSE 事件在支持相应能力的模型上均可用;citations_delta 当前普遍不返回。流式工具参数(input_json_delta)在部分模型上需先显式关闭 thinking 才可用。

stop_reason 枚举

含义
处理建议
end_turn
模型正常结束
正常处理。
max_tokens
达到 max_tokens 限制,输出被截断
增大 max_tokens 或分段生成。
stop_sequence
命中 stop_sequences
检查命中的 stop_sequence 字段。
tool_use
模型请求调用工具
执行工具,将结果以 tool_result 回传继续对话。
pause_turn
server tool 长轮次暂停
原样回传当前内容继续请求以恢复。
refusal
模型因安全原因拒答
检查输入是否触发安全策略。

Token 用量(usage)

字段
类型
说明
input_tokens
integer
净输入 token(不含缓存读写部分)
output_tokens
integer
输出 token(含 thinking 内容)
cache_creation_input_tokens
integer
写入缓存的 token 数
cache_read_input_tokens
integer
命中缓存读取的 token 数(计费大幅降低)
cache_creation.ephemeral_5m_input_tokens
integer
5 分钟 TTL 缓存创建 token(分 TTL 明细)
cache_creation.ephemeral_1h_input_tokens
integer
1 小时 TTL 缓存创建 token(分 TTL 明细)
server_tool_use.web_search_requests
integer
内置 web_search 调用次数
server_tool_use.web_fetch_requests
integer
内置 web_fetch 调用次数
service_tier
string
实际命中的服务层级
说明:
input_tokens 互斥规则:Anthropic 规范中 input_tokenscache_read_input_tokenscache_creation_input_tokens 三者互斥,真实总输入 = 三者之和。计算成本时需将三项相加,不要只看 input_tokens。 流式响应中,message_start 事件给出初始的 input_tokens 与缓存 token;message_delta 事件给出最终的 output_tokens

典型场景示例

说明:
所有示例统一请求入口:POST /v1/messages,需带 anthropic-versionx-api-key 头。以下 ${BASE_URL}https://tokenhub.tencentmaas.com

示例:基础对话

cURL
Python
Node.js
Java
Go
curl -s -X POST "${BASE_URL}/v1/messages" \\
-H 'Content-Type: application/json' \\
-H 'anthropic-version: 2023-06-01' \\
-H "x-api-key: ${API_KEY}" \\
-d '{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "你好" }],
"max_tokens": 1024
}'
import requests

resp = requests.post(
"https://tokenhub.tencentmaas.com/v1/messages",
headers={
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
json={
"model": "<your-model-name>",
"messages": [{"role": "user", "content": "你好"}],
"max_tokens": 1024,
},
)
print(resp.json())
const resp = await fetch("https://tokenhub.tencentmaas.com/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
body: JSON.stringify({
model: "<your-model-name>",
messages: [{ role: "user", content: "你好" }],
max_tokens: 1024,
}),
});
console.log(await resp.json());
import okhttp3.*;

public class BasicMessage {
public static void main(String[] args) throws Exception {
String body = """
{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "你好" }],
"max_tokens": 1024
}
""";

Request request = new Request.Builder()
.url("https://tokenhub.tencentmaas.com/v1/messages")
.header("Content-Type", "application/json")
.header("anthropic-version", "2023-06-01")
.header("x-api-key", "YOUR_API_KEY")
.post(RequestBody.create(body, MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
package main

import (
"fmt"
"io"
"net/http"
"strings"
)

func main() {
body := `{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "你好" }],
"max_tokens": 1024
}`

req, _ := http.NewRequest("POST",
"https://tokenhub.tencentmaas.com/v1/messages",
strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("anthropic-version", "2023-06-01")
req.Header.Set("x-api-key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()

data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}

示例:带 system + 流式

cURL
Python
Node.js
Java
Go
curl -s -N -X POST "${BASE_URL}/v1/messages" \\
-H 'Content-Type: application/json' \\
-H 'anthropic-version: 2023-06-01' \\
-H "x-api-key: ${API_KEY}" \\
-d '{
"model": "<your-model-name>",
"system": [{ "type": "text", "text": "你是一个友好的助手" }],
"messages": [{ "role": "user", "content": "1+1等于几?" }],
"max_tokens": 1024,
"stream": true
}'
import requests

resp = requests.post(
"https://tokenhub.tencentmaas.com/v1/messages",
headers={
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
json={
"model": "<your-model-name>",
"system": [{"type": "text", "text": "你是一个友好的助手"}],
"messages": [{"role": "user", "content": "1+1等于几?"}],
"max_tokens": 1024,
"stream": True,
},
stream=True,
)
for line in resp.iter_lines(decode_unicode=True):
if line:
print(line)
const resp = await fetch("https://tokenhub.tencentmaas.com/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
body: JSON.stringify({
model: "<your-model-name>",
system: [{ type: "text", text: "你是一个友好的助手" }],
messages: [{ role: "user", content: "1+1等于几?" }],
max_tokens: 1024,
stream: true,
}),
});
const reader = resp.body.getReader();
const decoder = new TextDecoder();
while (true) {
const { done, value } = await reader.read();
if (done) break;
process.stdout.write(decoder.decode(value));
}
import okhttp3.*;
import java.io.BufferedReader;
import java.io.InputStreamReader;

public class SystemStream {
public static void main(String[] args) throws Exception {
String body = """
{
"model": "<your-model-name>",
"system": [{ "type": "text", "text": "你是一个友好的助手" }],
"messages": [{ "role": "user", "content": "1+1等于几?" }],
"max_tokens": 1024,
"stream": true
}
""";

Request request = new Request.Builder()
.url("https://tokenhub.tencentmaas.com/v1/messages")
.header("Content-Type", "application/json")
.header("anthropic-version", "2023-06-01")
.header("x-api-key", "YOUR_API_KEY")
.post(RequestBody.create(body, MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute();
BufferedReader reader = new BufferedReader(
new InputStreamReader(response.body().byteStream()))) {
String line;
while ((line = reader.readLine()) != null) {
if (!line.isEmpty()) System.out.println(line);
}
}
}
}
package main

import (
"bufio"
"fmt"
"net/http"
"strings"
)

func main() {
body := `{
"model": "<your-model-name>",
"system": [{ "type": "text", "text": "你是一个友好的助手" }],
"messages": [{ "role": "user", "content": "1+1等于几?" }],
"max_tokens": 1024,
"stream": true
}`

req, _ := http.NewRequest("POST",
"https://tokenhub.tencentmaas.com/v1/messages",
strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("anthropic-version", "2023-06-01")
req.Header.Set("x-api-key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()

scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
if line := scanner.Text(); line != "" {
fmt.Println(line)
}
}
}
期望 SSE 事件链:message_start → content_block_start → content_block_delta → content_block_stop → message_delta → message_stop

示例:多轮对话

多轮对话需完整携带历史消息(平台不做会话管理):
{
"model": "<your-model-name>",
"messages": [
{ "role": "user", "content": "如何读取 CSV 文件?" },
{ "role": "assistant", "content": "使用 pandas:pd.read_csv('file.csv')" },
{ "role": "user", "content": "如果文件很大内存放不下怎么办?" }
],
"max_tokens": 1024
}

示例:多模态(图片理解)

理解图片(URL):
{
"model": "<your-model-name>",
"messages": [{
"role": "user",
"content": [
{ "type": "text", "text": "请详细描述图中的场景" },
{ "type": "image", "source": { "type": "url", "url": "https://example.com/photo.jpg" } }
]
}],
"max_tokens": 1024
}
Base64 图片:
{
"role": "user",
"content": [
{ "type": "text", "text": "识别图中的文字" },
{ "type": "image", "source": { "type": "base64", "media_type": "image/jpeg", "data": "/9j/4AAQSkZJRgAB..." } }
]
}

示例:工具调用

cURL
Python
Node.js
Java
Go
curl -s -X POST "${BASE_URL}/v1/messages" \\
-H 'Content-Type: application/json' \\
-H 'anthropic-version: 2023-06-01' \\
-H "x-api-key: ${API_KEY}" \\
-d '{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "北京今天天气怎么样?" }],
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "查询指定城市的天气信息",
"input_schema": {
"type": "object",
"properties": { "location": { "type": "string", "description": "城市名称" } },
"required": ["location"]
}
}],
"tool_choice": { "type": "auto" }
}'
import requests

resp = requests.post(
"https://tokenhub.tencentmaas.com/v1/messages",
headers={
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
json={
"model": "<your-model-name>",
"messages": [{"role": "user", "content": "北京今天天气怎么样?"}],
"max_tokens": 1024,
"tools": [
{
"name": "get_weather",
"description": "查询指定城市的天气信息",
"input_schema": {
"type": "object",
"properties": {"location": {"type": "string", "description": "城市名称"}},
"required": ["location"],
},
}
],
"tool_choice": {"type": "auto"},
},
)
print(resp.json())
const resp = await fetch("https://tokenhub.tencentmaas.com/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
body: JSON.stringify({
model: "<your-model-name>",
messages: [{ role: "user", content: "北京今天天气怎么样?" }],
max_tokens: 1024,
tools: [
{
name: "get_weather",
description: "查询指定城市的天气信息",
input_schema: {
type: "object",
properties: { location: { type: "string", description: "城市名称" } },
required: ["location"],
},
},
],
tool_choice: { type: "auto" },
}),
});
console.log(await resp.json());
import okhttp3.*;

public class ToolUse {
public static void main(String[] args) throws Exception {
String body = """
{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "北京今天天气怎么样?" }],
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "查询指定城市的天气信息",
"input_schema": {
"type": "object",
"properties": { "location": { "type": "string", "description": "城市名称" } },
"required": ["location"]
}
}],
"tool_choice": { "type": "auto" }
}
""";

Request request = new Request.Builder()
.url("https://tokenhub.tencentmaas.com/v1/messages")
.header("Content-Type", "application/json")
.header("anthropic-version", "2023-06-01")
.header("x-api-key", "YOUR_API_KEY")
.post(RequestBody.create(body, MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
package main

import (
"fmt"
"io"
"net/http"
"strings"
)

func main() {
body := `{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "北京今天天气怎么样?" }],
"max_tokens": 1024,
"tools": [{
"name": "get_weather",
"description": "查询指定城市的天气信息",
"input_schema": {
"type": "object",
"properties": { "location": { "type": "string", "description": "城市名称" } },
"required": ["location"]
}
}],
"tool_choice": { "type": "auto" }
}`

req, _ := http.NewRequest("POST",
"https://tokenhub.tencentmaas.com/v1/messages",
strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("anthropic-version", "2023-06-01")
req.Header.Set("x-api-key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()

data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
模型返回 tool_use 后,客户端执行工具并以 tool_result(放入 user 消息)回传:
{
"model": "<your-model-name>",
"messages": [
{ "role": "user", "content": "北京今天天气怎么样?" },
{ "role": "assistant", "content": [
{ "type": "tool_use", "id": "toolu_001", "name": "get_weather", "input": { "location": "北京" } }
]},
{ "role": "user", "content": [
{ "type": "tool_result", "tool_use_id": "toolu_001", "content": "北京今天晴天,25度" }
]}
],
"max_tokens": 1024,
"tools": [{
"name": "get_weather", "description": "查询天气",
"input_schema": { "type": "object", "properties": { "location": { "type": "string" } }, "required": ["location"] }
}]
}

示例:思维链

cURL
Python
Node.js
Java
Go
curl -s -X POST "${BASE_URL}/v1/messages" \\
-H 'Content-Type: application/json' \\
-H 'anthropic-version: 2023-06-01' \\
-H "x-api-key: ${API_KEY}" \\
-d '{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "请解释什么是递归" }],
"max_tokens": 4096,
"thinking": { "type": "enabled", "budget_tokens": 2048 }
}'
import requests

resp = requests.post(
"https://tokenhub.tencentmaas.com/v1/messages",
headers={
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
json={
"model": "<your-model-name>",
"messages": [{"role": "user", "content": "请解释什么是递归"}],
"max_tokens": 4096,
"thinking": {"type": "enabled", "budget_tokens": 2048},
},
)
print(resp.json())
const resp = await fetch("https://tokenhub.tencentmaas.com/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
body: JSON.stringify({
model: "<your-model-name>",
messages: [{ role: "user", content: "请解释什么是递归" }],
max_tokens: 4096,
thinking: { type: "enabled", budget_tokens: 2048 },
}),
});
console.log(await resp.json());
import okhttp3.*;

public class Thinking {
public static void main(String[] args) throws Exception {
String body = """
{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "请解释什么是递归" }],
"max_tokens": 4096,
"thinking": { "type": "enabled", "budget_tokens": 2048 }
}
""";

Request request = new Request.Builder()
.url("https://tokenhub.tencentmaas.com/v1/messages")
.header("Content-Type", "application/json")
.header("anthropic-version", "2023-06-01")
.header("x-api-key", "YOUR_API_KEY")
.post(RequestBody.create(body, MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
package main

import (
"fmt"
"io"
"net/http"
"strings"
)

func main() {
body := `{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "请解释什么是递归" }],
"max_tokens": 4096,
"thinking": { "type": "enabled", "budget_tokens": 2048 }
}`

req, _ := http.NewRequest("POST",
"https://tokenhub.tencentmaas.com/v1/messages",
strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("anthropic-version", "2023-06-01")
req.Header.Set("x-api-key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()

data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
响应 content 中会包含 thinking 块(带 signature)与 text 块。注意 max_tokens 须大于 budget_tokens

示例:多轮思维链(携带 signature)

多轮对话时,必须将上一轮 assistant 的 thinking 块连同 signature 原样回传:
{
"model": "<your-model-name>",
"messages": [
{ "role": "user", "content": "分析这段代码复杂度" },
{ "role": "assistant", "content": [
{ "type": "thinking", "thinking": "外层 n 次内层 log n 次...", "signature": "EqoBCkgIARgC..." },
{ "type": "text", "text": "O(n log n)" }
]},
{ "role": "user", "content": "如何优化成 O(n)?" }
],
"max_tokens": 4096,
"thinking": { "type": "enabled", "budget_tokens": 5000 }
}
注意:
关键signature 必须原样保留回传,否则服务报 400 Invalid signature

示例:内置工具(web_search)

cURL
Python
Node.js
Java
Go
curl -s -X POST "${BASE_URL}/v1/messages" \\
-H 'Content-Type: application/json' \\
-H 'anthropic-version: 2023-06-01' \\
-H "x-api-key: ${API_KEY}" \\
-d '{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "2026年有哪些新大模型?" }],
"max_tokens": 2048,
"tools": [{ "type": "web_search_20250305", "name": "web_search", "max_uses": 3 }]
}'
import requests

resp = requests.post(
"https://tokenhub.tencentmaas.com/v1/messages",
headers={
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
json={
"model": "<your-model-name>",
"messages": [{"role": "user", "content": "2026年有哪些新大模型?"}],
"max_tokens": 2048,
"tools": [{"type": "web_search_20250305", "name": "web_search", "max_uses": 3}],
},
)
print(resp.json())
const resp = await fetch("https://tokenhub.tencentmaas.com/v1/messages", {
method: "POST",
headers: {
"Content-Type": "application/json",
"anthropic-version": "2023-06-01",
"x-api-key": "YOUR_API_KEY",
},
body: JSON.stringify({
model: "<your-model-name>",
messages: [{ role: "user", content: "2026年有哪些新大模型?" }],
max_tokens: 2048,
tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }],
}),
});
console.log(await resp.json());
import okhttp3.*;

public class BuiltinTool {
public static void main(String[] args) throws Exception {
String body = """
{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "2026年有哪些新大模型?" }],
"max_tokens": 2048,
"tools": [{ "type": "web_search_20250305", "name": "web_search", "max_uses": 3 }]
}
""";

Request request = new Request.Builder()
.url("https://tokenhub.tencentmaas.com/v1/messages")
.header("Content-Type", "application/json")
.header("anthropic-version", "2023-06-01")
.header("x-api-key", "YOUR_API_KEY")
.post(RequestBody.create(body, MediaType.parse("application/json")))
.build();

try (Response response = new OkHttpClient().newCall(request).execute()) {
System.out.println(response.body().string());
}
}
}
package main

import (
"fmt"
"io"
"net/http"
"strings"
)

func main() {
body := `{
"model": "<your-model-name>",
"messages": [{ "role": "user", "content": "2026年有哪些新大模型?" }],
"max_tokens": 2048,
"tools": [{ "type": "web_search_20250305", "name": "web_search", "max_uses": 3 }]
}`

req, _ := http.NewRequest("POST",
"https://tokenhub.tencentmaas.com/v1/messages",
strings.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("anthropic-version", "2023-06-01")
req.Header.Set("x-api-key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()

data, _ := io.ReadAll(resp.Body)
fmt.Println(string(data))
}
说明:
内置工具通过 type 指定版本化类型名,无需 input_schema。内置工具的支持情况因模型而异,详情请参见 各模型字段兼容情况

示例:Prompt Caching

在 system 长文档或工具定义上打 cache_control 标记,命中缓存后大幅降低 input_tokens 计费:
{
"model": "<your-model-name>",
"system": [
{ "type": "text", "text": "你是一个文档问答助手。" },
{ "type": "text", "text": "<很长的文档内容...>", "cache_control": { "type": "ephemeral", "ttl": "1h" } }
],
"messages": [{ "role": "user", "content": "文档第三章讲了什么?" }],
"max_tokens": 1024
}
响应 usage 中可见 cache_creation_input_tokens(首次写缓存)与 cache_read_input_tokens(后续命中读取)。