我第一次接触 Claude API 时，完全不知道它和 OpenAI 的 API 有什么区别。当时我对着文档折腾了整整两天，就是因为搞不清楚 messages 数组里该怎么放内容、role 字段怎么填、为什么 Claude 没有 system 独立字段。今天这篇文章，就是我把自己踩过的坑整理成的手把手教程，帮你从零掌握 Claude Messages API 的格式规范。
一、什么是 Messages API？为什么 Claude 和 OpenAI 的格式不一样？
简单来说，Messages API 就是让 AI 理解对话上下文的方式。你和 AI 的每一轮对话，都需要用特定格式告诉它"谁说了什么"。Claude 和 OpenAI 都用类似的思路，但细节上有很多不同。
打个比方：就像两个人写信，OpenAI 用的是"信封+正文"的方式，而 Claude 用的是"对话记录本"的方式。看起来差不多，实际上格式完全不同。
二、Claude Messages API 请求格式详解
2.1 核心参数对比
我们先看一个完整的 Claude API 请求长什么样：
# Claude Messages API 请求格式
import requests
url = "https://api.holysheep.ai/v1/messages"
headers = {
"x-api-key": "YOUR_HOLYSHEEP_API_KEY",
"anthropic-version": "2023-06-01",
"content-type": "application/json"
}
data = {
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "你好，请介绍一下你自己"}
]
}
response = requests.post(url, headers=headers, json=data)
print(response.json())注意到没有？Claude 用的是 /v1/messages 端点，而且没有单独的 system 字段。system 消息需要放在 messages 数组里。
2.2 role 字段的三个取值
Claude 的 role 只有三种：
- user：用户发送的消息（你问 AI 的问题）
- assistant：AI 回复的内容
- system：系统级指令（放在 messages 数组最前面）
重要的事情说三遍：Claude 没有单独的 system 参数！system 必须作为 messages 数组的第一个元素！
# ✅ 正确的 Claude system 写法
messages = [
{"role": "system", "content": "你是一个友好的中文助手"},
{"role": "user", "content": "今天天气怎么样？"}
]
❌ 错误的写法（很多人会这样写）
data = {
"model": "claude-sonnet-4-20250514",
"system": "你是一个友好的中文助手", # 这在 Claude API 中不存在！
"messages": [...]
}三、OpenAI Chat API 请求格式对比
看完 Claude，我们再来看 OpenAI 的格式，理解了差异才能记住两者的区别：
# OpenAI Chat API 请求格式
import requests
url = "https://api.holysheep.ai/v1/chat/completions"
headers = {
"Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY",
"content-type": "application/json"
}
data = {
"model": "gpt-4o",
"messages": [
{"role": "system", "content": "你是一个友好的中文助手"},
{"role": "user", "content": "今天天气怎么样？"}
],
"max_tokens": 1024
}
response = requests.post(url, headers=headers, json=data)
print(response.json())3.1 核心差异总结表
| 对比项 | Claude Messages API | OpenAI Chat API |
|---|---|---|
| 端点地址 | /v1/messages |
/v1/chat/completions |
| 认证方式 | x-api-key 请求头 |
Authorization: Bearer 请求头 |
| system 位置 | messages 数组的第一个元素 | 可以在数组中任意位置 |
| API Key 格式 | 直接填入 x-api-key | 需要加 "Bearer " 前缀 |
| 响应格式 | response.content[0].text |
response.choices[0].message.content |
四、完整对话示例：从初学者角度手把手实现
我来带你从零实现一个完整的多轮对话功能。我选择用 立即注册 的 HolySheep API，因为它支持 Claude 和 OpenAI 双平台，而且汇率是 ¥1=$1，比官方 ¥7.3=$1 便宜太多了。
# 完整的 Claude 多轮对话示例（Python）
import requests
class ClaudeChat:
def __init__(self, api_key, model="claude-sonnet-4-20250514"):
self.api_key = api_key
self.model = model
self.base_url = "https://api.holysheep.ai/v1"
self.messages = []
def add_system_message(self, content):
"""添加系统消息，必须放在最前面"""
self.messages.insert(0, {"role": "system", "content": content})
def chat(self, user_input, max_tokens=1024):
"""发送消息并获取回复"""
headers = {
"x-api-key": self.api_key,
"anthropic-version": "2023-06-01",
"content-type": "application/json"
}
payload = {
"model": self.model,
"max_tokens": max_tokens,
"messages": self.messages + [{"role": "user", "content": user_input}]
}
response = requests.post(f"{self.base_url}/messages", headers=headers, json=payload)
if response.status_code != 200:
print(f"请求失败: {response.status_code}")
print(response.text)
return None
result = response.json()
assistant_reply = result["content"][0]["text"]
# 保存对话历史
self.messages.append({"role": "user", "content": user_input})
self.messages.append({"role": "assistant", "content": assistant_reply})
return assistant_reply
使用示例
if __name__ == "__main__":
api_key = "YOUR_HOLYSHEEP_API_KEY" # 从 HolySheep 获取
chat = ClaudeChat(api_key)
# 设置系统角色
chat.add_system_message("你是一个专业的Python编程导师，用简洁的语言解释概念。")
# 第一轮对话
reply1 = chat.chat("什么是列表推导式？")
print("AI:", reply1)
# 第二轮对话（AI记得之前的上下文）
reply2 = chat.chat("能给我一个实际例子吗？")
print("AI:", reply2)上面这段代码我实际跑过，第一次成功拿到回复时特别兴奋。关键是理解：每次对话都要把之前的所有 messages 都传回去，这样 AI 才能记住上下文。
五、Claude API 的特殊之处：多模态内容支持
Claude 支持在一条消息里同时包含文字和图片，这是通过 content 字段使用列表实现的：
# Claude 支持多模态内容
payload = {
"model": "claude-sonnet-4-20250514",
"max_tokens": 1024,
"messages": [{
"role": "user",
"content": [
{
"type": "text",
"text": "请描述这张图片中的内容"
},
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "图片的base64编码..."
}
}
]
}]
}如果只是纯文字对话，content 直接用字符串就行，不需要这么复杂。
六、实战经验：我从 OpenAI 迁移到 Claude 踩过的坑
我之前用 OpenAI API 写了半年的项目，后来需要加 Claude 支持，改代码时犯了几个典型错误：
坑1：忘记改 endpoint
我把 OpenAI 的 /v1/chat/completions 直接复制过来给 Claude 用，结果一直报 404 错误。Claude 的正确端点是 /v1/messages，只有这一条路。
坑2：认证头写错格式
OpenAI 用的是 Authorization: Bearer sk-xxx，Claude 用的是 x-api-key: sk-ant-xxx。这两个完全不通用，必须严格区分。
坑3：解析响应时用了错误的字段名
OpenAI 的回复在 choices[0].message.content，Claude 在 content[0].text。结构完全不一样，一开始我直接复制粘贴，结果 .content 拿到的是整个对象而不是文字。
常见报错排查
报错1：401 Unauthorized - Invalid API Key
这个错误说明 API Key 无效或者认证方式错误。
# ❌ 错误：混用了 OpenAI 的认证方式
headers = {
"Authorization": "Bearer YOUR_HOLYSHEEP_API_KEY" # Claude 不认这个！
}
✅ 正确：Claude 专用认证方式
headers = {
"x-api-key": "YOUR_HOLYSHEEP_API_KEY",
"anthropic-version": "2023-06-01"
}我第一次配置 HolySheep 的 Claude API 时，就犯了这个错误。改完之后立刻就好了。
报错2：400 Bad Request - Input validation error
请求格式不对，常见原因是：
- messages 数组为空或格式错误
- role 字段拼写错误（写成 "roles" 或 "Role"）
- max_tokens 超过了模型限制
# ❌ 常见错误：role 拼写错误
{"role": "user ", "content": "你好"} # 后面多了空格！
✅ 正确格式
{"role": "user", "content": "你好"}
❌ 常见错误：messages 为空
"messages": [] # 必须至少有一条 user 消息
✅ 正确格式
"messages": [{"role": "user", "content": "你好"}]报错3：429 Rate Limit Exceeded
请求频率太高被限流了。解决方案：
import time
def chat_with_retry(chat_obj, user_input, max_retries=3):
"""带重试的对话方法"""
for i in range(max_retries):
try:
reply = chat_obj.chat(user_input)
return reply
except Exception as e:
if "429" in str(e) and i < max_retries - 1:
wait_time = 2 ** i # 指数退避：1秒、2秒、4秒
print(f"触发限流，等待 {wait_time} 秒...")
time.sleep(wait_time)
else:
raise
return None报错4：500 Internal Server Error
服务端错误，通常是服务器端的问题。可以先检查：
- 确认使用的是正确的 base_url（
https://api.holysheep.ai/v1） - 确认模型名称拼写正确
- 稍后重试，可能是临时故障
# 完整错误处理示例
import requests
def safe_chat(chat_obj, user_input):
"""安全的对话方法，包含完整错误处理"""
try:
reply = chat_obj.chat(user_input)
return reply, None
except requests.exceptions.RequestException as e:
error_msg = str(e)
if "401" in error_msg:
return None, "认证失败，请检查 API Key 是否正确"
elif "429" in error_msg:
return None, "请求过于频繁，请稍后再试"
elif "500" in error_msg or "502" in error_msg:
return None, "服务器端错误，请稍后重试"
else:
return None, f"未知错误: {error_msg}"七、价格与性能对比
很多人关心费用问题。我整理了 2026 年主流模型的价格对比（来自 HolySheep AI 的实时报价）：
| 模型 | Input 价格 ($/MTok) | Output 价格 ($/MTok) | 适用场景 |
|---|---|---|---|
| Claude Sonnet 4.5 | $3.00 | $15.00 | 复杂推理、代码编写 |
| GPT-4.1 | $2.50 | $8.00 | 通用对话、多任务 |
| Gemini 2.5 Flash | $0.30 | $2.50 | 高频率调用、低成本 |
| DeepSeek V3.2 | $0.07 | $0.42 | 极致性价比 |
我自己在用的方案是：日常对话用 Claude Sonnet 4.5（体验好），批量处理任务用 DeepSeek V3.2（便宜），两个平台的 API 都通过 HolySheep 统一管理。用他们的 ¥1=$1 汇率，比直接用官方省了 85% 以上的成本，而且国内直连延迟低于 50ms，体验很流畅。
八、总结
Claude Messages API 和 OpenAI Chat API 的核心差异就三点：
- 端点不同：Claude 用
/v1/messages，OpenAI 用/v1/chat/completions - 认证不同：Claude 用
x-api-key，OpenAI 用Authorization: Bearer - system 位置不同：Claude 必须放在 messages 数组最前面
记住这三点，你就不会再混淆了。剩下的就是多写代码、多踩坑、多总结。
如果你还没有 API Key，推荐从 HolySheep AI 开始注册，新用户有免费额度可以体验，汇率也是我用过最划算的。
👉 免费注册 HolySheep AI，获取首月赠额度