Claude API curl 示例：消息、流式、图片与工具调用的可复制请求（2026）

一个能跑通的 Claude API curl 示例只需要一次 POST 请求：地址是 https://api.anthropic.com/v1/messages，带三个请求头（x-api-key、anthropic-version: 2023-06-01、content-type: application/json），JSON 请求体里写 model、max_tokens 和 messages。下面先给可直接复制的版本，再给流式、图片、工具、token 计数和排错的变体。

curl 是区分「密钥和网络有没有问题」与「SDK 有没有配对」最快的办法。本文每条命令都按 Anthropic 官方文档（platform.claude.com）里的请求结构写成，导出 ANTHROPIC_API_KEY 之后即可原样运行。如果你想看概念讲解而不是命令手册，可以先读 Claude API 怎么用。

最小可用的 Claude API curl 示例

先导出一次密钥，避免它出现在命令历史或脚本里：

export ANTHROPIC_API_KEY="your-api-key-here"

然后发送一条消息。这是 Anthropic 入门指南里的请求：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1000,
    "messages": [
      {"role": "user", "content": "Explain what an HTTP 429 means in one sentence."}
    ]
  }'

各部分的作用：

读懂返回结果

调用成功会返回一个 JSON 对象。按 Anthropic 入门指南，结构如下（正文已省略）：

{
  "model": "claude-opus-5",
  "id": "msg_013mHbppMPd2PrVJzGMZPt2D",
  "type": "message",
  "role": "assistant",
  "content": [{"type": "text", "text": "..."}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 21, "output_tokens": 305}
}

content 是内容块数组而不是字符串，所以用 jq 取出文本，不要直接读原始返回：

curl -sS https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 300,
       "messages": [{"role": "user", "content": "Name three HTTP status codes."}]}' \
  | jq -r '.content[] | select(.type == "text") | .text'

回答看起来被截断时，先看 stop_reason。值为 max_tokens 表示碰到了你设的上限，而不是模型自然结束。计费依据是 usage 字段。

常见请求类型的 Claude API curl 示例

系统提示词与多轮对话

系统提示词是顶层的 system 字段，不是一条消息。之前的轮次按顺序放进 messages，最后一条必须是 user：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 500,
    "system": "You are a concise assistant for backend engineers.",
    "messages": [
      {"role": "user", "content": "What does idempotent mean for an API?"},
      {"role": "assistant", "content": "Repeating the same request has the same effect as sending it once."},
      {"role": "user", "content": "Give one example with HTTP methods."}
    ]
  }'

API 在两次调用之间不保存状态，所以每次请求都要重发你希望模型看到的历史。数组不要以 assistant 结尾：Anthropic 错误文档说明，Claude 4.6 及之后的模型会对「预填最后一条 assistant 消息」返回 400。

用 curl 做流式输出

在请求体里加 "stream": true。下面是 Anthropic 流式指南中的请求，额外加上 curl 的 -N（关闭缓冲）参数，事件会随到随打印，而不是攒成一块再输出：

curl -N https://api.anthropic.com/v1/messages \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -d '{
    "model": "claude-opus-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 256,
    "stream": true
  }'

输出是服务器推送事件（SSE）。Anthropic 文档给出的顺序是：先 message_start，然后每个内容块依次是 content_block_start、一个或多个 content_block_delta、content_block_stop，接着一个或多个 message_delta，最后 message_stop，中间可能夹杂 ping 事件。文本在 text_delta 里，message_delta 中的 usage 是累计值。Anthropic 也注明 curl 没有一条命令就能把流拼成完整消息的办法，所以把它当作观察工具即可。在代码里消费流的方法见我们的 Claude API 流式输出指南。

通过 URL 发送图片

图片以内容块的形式放在 user 消息里。这是 Anthropic 视觉指南中的 URL 来源示例：

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{
      "role": "user",
      "content": [
        {"type": "image", "source": {"type": "url", "url": "https://platform.claude.com/docs/images/vision-example.jpg"}},
        {"type": "text", "text": "Describe this image."}
      ]
    }]
  }'

本地文件用 base64 来源（"type": "base64"、"media_type": "image/jpeg"、"data": "..."）。Anthropic 列出的支持格式为 JPEG、PNG、GIF 和 WebP。base64 内容很长，这时下文「引号」一节里的 heredoc 写法就派上用场。

定义一个工具

工具在顶层 tools 数组里声明，输入用 JSON Schema 描述。下面沿用 Anthropic 文档中常见的 get_weather 示例：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "The city and state, e.g. San Francisco, CA"}
        },
        "required": ["location"]
      }
    }],
    "messages": [{"role": "user", "content": "What is the weather like in San Francisco?"}]
  }'

模型决定调用工具时，返回的 stop_reason 为 tool_use，并带一个 tool_use 内容块，含 id、工具 name 和 input 对象。工具由你自己执行，然后发一个新请求：追加这条 assistant 回合，再加一条 user 回合，里面放 tool_result 块，其 tool_use_id 与前面的 id 一致。

发送前先数 token

token 计数接口接受与消息请求相同的输入，不需要 max_tokens，只返回一个计数。以下来自 Anthropic token 计数指南：

curl https://api.anthropic.com/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "system": "You are a scientist",
    "messages": [{"role": "user", "content": "Hello, Claude"}]
  }'

返回只有一个字段，例如 {"input_tokens": 14}。Anthropic 将 token 计数列为免费，但它有独立于消息创建的每分钟请求数限制。

列出可用模型

用同样的两个鉴权头发一个 GET 请求，就能拿到你的密钥可用的模型，按发布时间从新到旧排列：

curl https://api.anthropic.com/v1/models \
  -H "anthropic-version: 2023-06-01" \
  -H "x-api-key: $ANTHROPIC_API_KEY"

Anthropic 参考文档列出了 limit（默认 20，最大 1000）以及用于翻页的 after_id 和 before_id。每一项包含模型 id、display_name 和 capabilities 对象。先跑这一条，是在遇到 404 之前确认模型 ID 最快的方式。

排查失败的 curl 请求

只打印状态行和响应头、丢弃正文。这个写法来自 Anthropic 错误文档：

curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "Hello, Claude"}]}'

每个响应都带 request-id 头，联系支持时附上它。错误以 JSON 返回，顶层 error 对象包含 type 和 message，另有 request_id 字段。按 Anthropic 错误文档，最常遇到的状态码如下：

遇到 400 时，message 通常会点名出错的字段，常见情况见我们的 Claude API 400 错误指南。401 和 403 请看 Anthropic API 密钥无法使用。

Shell 引号的常见坑

大多数跑不通的 curl 示例，问题出在 shell 而不是 API：

• 单引号里的变量不会展开。 $ANTHROPIC_API_KEY 放在双引号的请求头里没问题，但放进单引号的 -d '...' 请求体里，会被原样发送。
• 撇号会提前结束单引号。 Anthropic 自己的示例用 What'\''s 在 -d '...' 里放入撇号。换个说法可以直接避开。
• 大请求体或程序生成的请求体放进 heredoc 或文件。 Anthropic 的 base64 示例用 -d @- <<EOF，让 shell 变量能在 JSON 里展开。也可以把请求体写进 request.json，再用 -d @request.json 传入。
• 先验证 JSON，再怀疑 API。 用 jq . 过一遍请求体，发现多余的逗号比读 400 报错快得多。

把同一条 curl 指向网关

如果你通过提供 Anthropic 兼容端点的代理或网关访问 Claude，请求体完全不变，只需换主机地址和密钥；部分网关除了 x-api-key 也接受 Authorization: Bearer。先核对哪些事项见我们的 Claude API 代理指南；ROIBest AI 的具体 base URL 与请求头写法，见 用 SDK 和 curl 直接调用网关。

常见问题

Claude API 的 curl 请求需要哪些请求头？

三个：带 API 密钥的 x-api-key、值为 2023-06-01 的 anthropic-version，以及有 JSON 请求体时的 content-type: application/json。列出模型的 GET 请求只需要前两个。

为什么我的 Claude API curl 请求返回 401？

按 Anthropic 错误文档，原因是密钥缺失、格式错误、已吊销或已过期。检查变量是否在同一个 shell 里导出，并且是在双引号而不是单引号里引用。

怎样用 curl 流式获取 Claude API 的回答？

在 JSON 请求体里加 "stream": true，并用 curl -N 关闭输出缓冲。你会收到服务器推送事件，文本在 content_block_delta 事件的 text_delta 里。

调用 Messages API 时 max_tokens 必须填吗？

必须。Messages 接口上 model、max_tokens 和 messages 都是必填项。token 计数接口是例外，它的示例里没有 max_tokens。