第 7 章
Messages API 全参数解析：27个参数的作用、默认值与最佳实践
第七章：Messages API 完全参考：参数、版本与兼容性
7.1 Messages API 概览
POST https://api.anthropic.com/v1/messages 是 Claude 的核心 API 端点。理解其每个参数的精确语义，是构建可靠生产系统的基础。本章系统梳理所有参数的作用、默认值、限制和注意事项。
请求结构总览
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [...],
"system": "...",
"temperature": 1.0,
"top_p": null,
"top_k": null,
"stop_sequences": [],
"stream": false,
"tools": [],
"tool_choice": {"type": "auto"},
"thinking": null,
"metadata": {},
"betas": []
}
响应结构总览
{
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{"type": "text", "text": "..."},
{"type": "tool_use", "id": "toolu_...", "name": "...", "input": {}}
],
"model": "claude-sonnet-4-6",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 100,
"output_tokens": 200,
"cache_creation_input_tokens": 0,
"cache_read_input_tokens": 0
}
}
7.2 必需参数
model（必需）
指定要使用的模型 ID。
# 当前主要模型 ID（2025年）
MODELS = {
# 最强推理能力
"claude-opus-4-6": {
"context": 200_000,
"thinking": True,
"vision": True,
"input_price": 15.0, # $/M tokens
"output_price": 75.0,
},
# 生产推荐默认值
"claude-sonnet-4-6": {
"context": 200_000,
"thinking": True,
"vision": True,
"input_price": 3.0,
"output_price": 15.0,
},
# 高速低成本
"claude-haiku-4-5-20251001": {
"context": 200_000,
"thinking": False,
"vision": True,
"input_price": 0.25,
"output_price": 1.25,
},
}
重要细节：
- 模型 ID 区分大小写
- 使用不含日期戳的 ID（如
claude-sonnet-4-6）会指向该版本的最新快照，可能随时间变化 - 对于要求响应稳定性的生产系统，建议使用带日期戳的固定版本（如果 Anthropic 为该版本提供）
max_tokens（必需）
控制模型在这次响应中最多可生成的 token 数。
# 不同模型的 max_tokens 上限
MAX_TOKENS_LIMITS = {
"claude-opus-4-6": 32_000, # 普通模式
# 开启 extended thinking 时最多 32K，思考 tokens 不计入此限制
"claude-sonnet-4-6": 64_000,
"claude-haiku-4-5-20251001": 8_192,
}
# 注意：max_tokens 是上限，不是目标值
# 模型会在内容完成时提前停止（stop_reason = "end_turn"）
# 只有在达到上限时才会截断（stop_reason = "max_tokens"）
常见错误：设置过低的 max_tokens 导致响应被截断：
import anthropic
client = anthropic.Anthropic()
# 危险：如果实际响应需要 2000 tokens，这会截断输出
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=100, # ← 过低
messages=[{"role": "user", "content": "详细解释量子计算的工作原理"}]
)
# 检查是否被截断
if response.stop_reason == "max_tokens":
print("警告：响应被截断！考虑增加 max_tokens")
messages（必需）
对话历史数组。每条消息是一个包含 role 和 content 的对象。
role 枚举值：
"user"：用户消息（每次对话至少有一条）"assistant"：助手消息（用于多轮对话历史）
content 的两种形式：
# 形式一：字符串（简单文本）
{"role": "user", "content": "你好"}
# 形式二：内容块数组（支持多模态）
{
"role": "user",
"content": [
{"type": "text", "text": "描述这张图片"},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQ..." # base64 编码的图片
}
}
]
}
# 图片也可以通过 URL 引用（需要公开可访问）
{
"type": "image",
"source": {
"type": "url",
"url": "https://example.com/image.jpg"
}
}
消息顺序规则：
- 必须以 user 消息开始
- user 和 assistant 消息必须交替出现
- 不能有连续的 user 消息或连续的 assistant 消息
- 最后一条消息必须是 user 消息（除非使用 assistant prefill）
# 有效的消息序列
messages = [
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "你好！有什么我能帮你的吗？"},
{"role": "user", "content": "解释 REST API"}
]
# 无效：连续的 user 消息（会报 400 错误）
messages_invalid = [
{"role": "user", "content": "你好"},
{"role": "user", "content": "你在吗"} # ← 错误！
]
# 修复：合并连续的用户消息
messages_fixed = [
{"role": "user", "content": "你好，你在吗？"}
]
7.3 可选参数：采样控制
temperature
控制输出的随机性/创意性。范围 0.0-1.0（扩展思考模式强制为 1.0）。
temperature 的直观含义：
0.0 → 最确定性（每次相同输入输出最可能的结果）
0.5 → 平衡
1.0 → 最随机/创意（Claude 的默认值）
实用参考值：
代码生成/数学：0.0-0.2（需要精确，不想随机）
事实问答：0.0-0.3
摘要/提取：0.0-0.5
对话聊天：0.5-0.8
创意写作：0.7-1.0
头脑风暴：0.9-1.0
# 代码生成：低 temperature 确保可重复性
code_response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
temperature=0.1, # 接近确定性
messages=[{"role": "user", "content": "写一个二分查找的 Python 实现"}]
)
# 创意写作：高 temperature 增加多样性
story_response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=2048,
temperature=0.9,
messages=[{"role": "user", "content": "写一个关于时间旅行者的短故事开头"}]
)
注意：temperature 不等于"质量控制"。低 temperature 不能修复有缺陷的 prompt，高 temperature 不会让好 prompt 更差（只是更有创意）。
top_p 和 top_k
核采样参数，通常不需要同时使用多个采样参数：
# top_p (nucleus sampling)：只从累计概率达到 top_p 的 token 中采样
# 默认值：不设置（即使用 1.0）
# 当 top_p=0.9 时，只考虑累计概率前 90% 的 token
# top_k：只从概率最高的 k 个 token 中采样
# 默认值：不设置
# 当 top_k=50 时，只考虑概率最高的 50 个 token
# Anthropic 的建议：只调整其中之一，不要同时修改多个采样参数
# 对于大多数用例，只调 temperature 就足够了
stop_sequences
指定一个字符串列表。当模型输出中出现任意一个字符串时，立即停止生成。
# 常见用途：强制单行输出
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=100,
stop_sequences=["\n"], # 在第一个换行符处停止
messages=[{"role": "user", "content": "用一句话描述 Python 语言"}]
)
# 用途二：强制停在特定标记处
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
stop_sequences=["</answer>"], # 在结束标签处停止，避免生成多余内容
messages=[{
"role": "user",
"content": "回答以下问题，将答案放在 <answer> 标签中。问题：什么是哈希表？"
}],
)
# 检查是否因 stop_sequence 停止
if response.stop_reason == "stop_sequence":
print(f"停止于：{response.stop_sequence!r}")
最多可指定 4 个停止序列，每个最长 256 字符。
7.4 系统提示（system）
系统提示支持两种形式：
# 形式一：字符串
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system="你是一个有帮助的助手。",
messages=[...]
)
# 形式二：内容块数组（支持缓存控制）
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
system=[
{
"type": "text",
"text": "你是一个有帮助的助手。\n\n" + large_reference_doc,
"cache_control": {"type": "ephemeral"} # 启用缓存
}
],
messages=[...]
)
系统提示的内容类型限制：只允许文本块，不允许图片或工具结果。
7.5 工具相关参数
tools
定义模型可以调用的工具列表。每个工具包含：
tools = [
{
"name": "get_weather", # 工具名称（字母数字下划线）
"description": "获取指定城市的当前天气", # 工具功能描述
"input_schema": { # 参数的 JSON schema
"type": "object",
"required": ["city"],
"properties": {
"city": {
"type": "string",
"description": "城市名称，如 '北京'、'上海'"
},
"units": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "温度单位，默认 celsius"
}
}
}
}
]
tool_choice
控制模型是否/如何使用工具：
# 自动决定（默认）：模型根据对话内容决定是否调用工具
tool_choice = {"type": "auto"}
# 强制使用任意一个工具
tool_choice = {"type": "any"}
# 强制使用特定工具
tool_choice = {"type": "tool", "name": "get_weather"}
# 禁止使用工具（即使定义了工具）
tool_choice = {"type": "none"}
完整的工具调用流程
import anthropic
import json
client = anthropic.Anthropic()
def get_weather(city: str, units: str = "celsius") -> dict:
"""模拟天气 API"""
return {
"city": city,
"temperature": 22 if units == "celsius" else 72,
"condition": "晴天",
"humidity": 65
}
def chat_with_tools(user_message: str) -> str:
tools = [{
"name": "get_weather",
"description": "获取城市的当前天气信息",
"input_schema": {
"type": "object",
"required": ["city"],
"properties": {
"city": {"type": "string"},
"units": {"type": "string", "enum": ["celsius", "fahrenheit"]}
}
}
}]
messages = [{"role": "user", "content": user_message}]
# 第一轮：模型决定是否调用工具
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=messages
)
# 处理工具调用
while response.stop_reason == "tool_use":
# 将 assistant 响应加入历史
messages.append({"role": "assistant", "content": response.content})
# 处理所有工具调用
tool_results = []
for block in response.content:
if block.type == "tool_use":
# 执行工具
if block.name == "get_weather":
result = get_weather(**block.input)
else:
result = {"error": f"未知工具: {block.name}"}
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": json.dumps(result, ensure_ascii=False)
})
# 将工具结果加入历史
messages.append({"role": "user", "content": tool_results})
# 下一轮：模型根据工具结果生成响应
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
tools=tools,
messages=messages
)
# 返回最终文本响应
return next(
(block.text for block in response.content if block.type == "text"),
""
)
print(chat_with_tools("北京今天天气怎么样？"))
7.6 Extended Thinking 参数
thinking
为支持的模型（Opus 和 Sonnet）开启扩展思考：
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=16_000,
thinking={
"type": "enabled",
"budget_tokens": 10_000 # 分配给思考过程的最大 token 数
},
messages=[{"role": "user", "content": "证明勾股定理有多少种方法？请列举至少 5 种。"}]
)
# 响应包含两种类型的内容块
for block in response.content:
if block.type == "thinking":
print(f"[思考过程]\n{block.thinking[:500]}...\n")
elif block.type == "text":
print(f"[最终答案]\n{block.text}")
# 使用注意事项：
# 1. budget_tokens 必须 >= 1024
# 2. max_tokens 必须 > budget_tokens
# 3. 思考 tokens 按输出价格计费
# 4. 开启思考时 temperature 强制为 1.0
# 5. 思考模式下不支持 top_p 和 top_k
思考块的 API 处理
在多轮对话中，思考块可以传回 API（不必须，但有助于保持推理连续性）：
def multi_turn_with_thinking(questions: list[str]) -> list[str]:
"""多轮对话中保留思考历史"""
messages = []
answers = []
for question in questions:
messages.append({"role": "user", "content": question})
response = client.messages.create(
model="claude-opus-4-6",
max_tokens=8000,
thinking={"type": "enabled", "budget_tokens": 4000},
messages=messages
)
# 将完整的 assistant 响应（包含思考块）加入历史
messages.append({
"role": "assistant",
"content": response.content # 包含 thinking 和 text 块
})
# 提取文本答案
text = next((b.text for b in response.content if b.type == "text"), "")
answers.append(text)
return answers
7.7 请求元数据
metadata
向请求附加任意元数据，用于日志追踪和审计：
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
metadata={
"user_id": "usr_12345", # 可选的最终用户 ID
"session_id": "sess_abc",
"request_source": "mobile_app",
"feature_flag": "new_prompt_v2"
},
messages=[{"role": "user", "content": "..."}]
)
user_id 字段有特殊意义：Anthropic 可能用它来检测滥用行为，并在发现问题时更精准地限制特定用户而非整个 API key。
API 版本头
每个请求都需要 anthropic-version 头（SDK 自动添加）：
# SDK 自动添加正确的版本头
# 当前版本：2023-06-01
# 直接使用 HTTP 时需要手动指定：
# -H "anthropic-version: 2023-06-01"
betas（Beta 功能）
某些实验性功能需要显式开启 Beta 标志：
# 示例：开启某个 beta 功能（具体名称以官方文档为准）
response = client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
betas=["feature-name-2024-01"], # beta 功能标识符
messages=[...]
)
7.8 版本兼容性与迁移
API 版本策略
Anthropic 的 API 版本策略：
版本格式：YYYY-MM-DD（如 2023-06-01）
版本兼容性保证：
- 已发布的版本不会破坏性变更
- 新功能在现有版本中添加（向后兼容）
- 废弃通知提前至少 6 个月
目前只有一个稳定版本：2023-06-01
模型版本迁移指南
当 Anthropic 发布新模型版本时，迁移注意事项：
# 版本迁移安全检查清单
def validate_model_migration(old_model: str, new_model: str, test_cases: list) -> dict:
"""
在切换模型版本前，验证新版本与旧版本的行为一致性
"""
results = {"passed": 0, "failed": 0, "regressions": []}
for case in test_cases:
old_response = client.messages.create(
model=old_model,
max_tokens=1024,
messages=[{"role": "user", "content": case["prompt"]}]
)
new_response = client.messages.create(
model=new_model,
max_tokens=1024,
messages=[{"role": "user", "content": case["prompt"]}]
)
old_text = old_response.content[0].text
new_text = new_response.content[0].text
# 基础检查：格式是否保持（如果期望结构化输出）
if "expected_format" in case:
try:
import json
json.loads(new_text)
results["passed"] += 1
except json.JSONDecodeError:
results["failed"] += 1
results["regressions"].append({
"prompt": case["prompt"][:100],
"issue": "新模型输出不是有效 JSON"
})
return results
7.9 错误码完全参考
HTTP 状态码 错误类型 含义
──────────── ───────────────────── ─────────────────────
400 invalid_request_error 请求格式错误（参数无效）
401 authentication_error API Key 无效或缺失
403 permission_error 权限不足（通常是内容策略）
404 not_found_error 模型 ID 不存在
413 request_too_large 请求体超过大小限制
422 unprocessable_entity_error 内容违反使用政策
429 rate_limit_error 超过速率限制
500 api_error Anthropic 服务端错误
529 overloaded_error 服务过载（临时）
解读常见 400 错误
# 导致 400 错误的常见原因：
# 1. max_tokens 超过模型上限
client.messages.create(
model="claude-haiku-4-5-20251001",
max_tokens=100_000, # Haiku 上限 8192！
messages=[...]
)
# 2. messages 格式违反交替规则
client.messages.create(
model="claude-sonnet-4-6",
max_tokens=1024,
messages=[
{"role": "user", "content": "问题一"},
{"role": "user", "content": "问题二"}, # 连续 user 消息 → 400
]
)
# 3. 总输入超过模型上下文窗口
# system(50K) + messages(180K) > 200K → 400
# 4. thinking + stop_sequences 同时使用（不支持）
client.messages.create(
model="claude-opus-4-6",
max_tokens=5000,
thinking={"type": "enabled", "budget_tokens": 2000},
stop_sequences=["END"], # 思考模式不支持 stop_sequences → 400
messages=[...]
)
小结
Messages API 的参数设计反映了 Anthropic 在灵活性和安全性之间的取舍：
必需参数（model + max_tokens + messages）构成最小有效请求。
采样参数（temperature/top_p/top_k/stop_sequences）控制输出的随机性和终止条件。对于大多数应用，只需要调整 temperature。
系统提示（system）是定义模型行为的核心工具，支持缓存控制来优化高频请求的成本。
工具调用（tools + tool_choice）是实现 agentic 工作流的基础，完整的调用循环需要处理 stop_reason == "tool_use" 的状态。
扩展思考（thinking）为复杂推理任务提供额外的推理 token 预算，仅 Opus 和 Sonnet 支持。
下一章将专注于多轮对话的管理：如何在保持上下文质量的同时控制历史长度，以及会话持久化的最佳实践。