首次请求详解
逐行讲解一次 Messages 调用——每个字段的作用以及返回内容。
快速入门帮助你获得响应。本页解释其中各部分的含义，让你能够自行编写下一个请求。
请求
curl https://aiprimetech.io/v1/messages \
-H "x-api-key: $CLAUDEAPIKEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [{"role": "user", "content": "Hello"}]
}'| 字段 | 必填 | 作用 |
|---|---|---|
model | 是 | 指定要运行的模型。必须与以下来源中的某个 ID /v1/models 完全一致。 |
max_tokens | 是 | 设定以下内容的硬性上限： 输出。模型达到此上限时就会停止，即使句子尚未完成。这是成本控制上限，而非目标值。 |
messages | 是 | 截至目前的对话，按时间从早到晚排列。每条记录都有一个 role (user 或 assistant）以及 content. |
system | 否 | 适用于整个对话的指令。这是顶层字段，而不是带有以下属性的消息： role: system. |
temperature | 否 | 0–1。值越低，结果越确定。除非有明确理由，否则请保持未设置。 |
stream | 否 | true 返回服务器发送事件，而不是单个 JSON 响应体。请参阅 流式传输. |
响应
{
"id": "msg_01ABC...",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [{"type": "text", "text": "Hello! How can I help?"}],
"stop_reason": "end_turn",
"usage": {"input_tokens": 9, "output_tokens": 12}
}content是数组，而不是字符串。文本位于content[0].text。将其当作字符串处理是最常见的客户端错误。stop_reason说明生成结束的原因：end_turn（已完成）、max_tokens（达到你设置的上限，回复被截断）、stop_sequence，或tool_use.usage是计费依据。请记录它；这是成本归属分析唯一可靠的依据。
如果
stop_reason 是 max_tokens，说明你的回答被截断了。请提高 max_tokens 或要求更简短的回复。不要盲目重试，被截断的输出也会计费。多轮对话
API 是无状态的。要继续对话，你需要重新发送完整历史记录，包括模型之前的回复：
{
"model": "claude-sonnet-4-6",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "What is the capital of France?"},
{"role": "assistant", "content": "Paris."},
{"role": "user", "content": "And its population?"}
]
}