> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude 协议：Anthropic Messages 请求格式与 SDK

> 通过 /v1/messages 以 Anthropic Messages 格式调用老张API：认证头、cURL 与 Python SDK 示例、content 读取、流式输出和工具调用。

Claude 协议指 Anthropic Messages API 的请求格式。Anthropic SDK、Claude Code 等客户端只需改 Base URL、换上老张API密钥即可接入。

| 项目 | 内容 |
| - | - |
| 端点 | `POST https://api.laozhang.ai/v1/messages` |
| SDK Base URL | `https://api.laozhang.ai` |
| 必填字段 | `model`、`messages`、`max_tokens` |
| 回复格式 | 内容块数组 `content[]` |
| 可用模型 | 「兼容端点」包含 Anthropic Messages 的模型，见[可用模型](#可用模型) |
| 本页示例模型 | `glm-5.2` |

<Note>
  Claude 模型自 2026 年 9 月 24 日起未在老张API上架，上架时会在[网站公告](/changelog)通知。
</Note>

## 可用模型

[模型与价格总表](/models)中「兼容端点」包含 Anthropic Messages 的模型可以使用本协议。2026 年 9 月 24 日公开价格配置中，这类模型有：

* `glm-5.2`（`claude_code` 与 `default` 分组）：通过本协议调用时，请求与响应的行为与官方 Messages API 基本一致；
* `deepseek-v4-pro`；
* `deepseek-v4-flash` 等。

模型 ID 从总表或控制台完整复制，不要按产品名、Bedrock ID 或 Vertex ID 自行拼接。同一模型如果也标注了「OpenAI 兼容」，也可以用 [OpenAI 协议](/api-reference/chat-completions)调用；两种协议的请求体和响应字段不同，不能混用。

## 请求地址与认证

```text theme={null}
POST https://api.laozhang.ai/v1/messages
```

cURL 等直接发送 HTTP 请求时，带上以下三个请求头：

| 请求头 | 值 |
| - | - |
| `Authorization` | `Bearer` 加老张API密钥 |
| `anthropic-version` | `2023-06-01` |
| `content-type` | `application/json` |

在[令牌管理](https://api.laozhang.ai/token)创建 API Key，计费模式选择按量优先（推荐）或按量计费，并确认令牌分组可以调用所选模型，然后写入环境变量：

```bash theme={null}
export LAOZHANG_API_KEY="替换为你的老张API密钥"
```

请求体的要求：

* 必须包含 `model`、`messages` 和 `max_tokens`；
* 系统提示放在顶层 `system` 字段；
* `messages` 中只使用 `user` 和 `assistant` 两种角色。

## 发送消息

使用 Python 示例时，先执行 `python -m pip install anthropic`。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 120 \
      "https://api.laozhang.ai/v1/messages" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{
        "model": "glm-5.2",
        "max_tokens": 1024,
        "system": "你是一名简洁的技术助手。",
        "messages": [
          {"role": "user", "content": "请只回复：连接成功"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from anthropic import Anthropic

    client = Anthropic(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai",
        timeout=120.0,
        max_retries=0,
    )
    message = client.messages.create(
        model="glm-5.2",
        max_tokens=1024,
        system="你是一名简洁的技术助手。",
        messages=[{"role": "user", "content": "请只回复：连接成功"}],
    )
    for block in message.content:
        if block.type == "text":
            print(block.text)
    ```
  </Tab>
</Tabs>

Anthropic SDK 的 `base_url` 只写域名根，SDK 会自己拼接 `/v1/messages`，并自动发送认证头和 `anthropic-version`。示例关闭了自动重试，由应用决定失败后是否重发。

## 读取 content 内容块

回复位于 `content[]`，每个元素是一个带 `type` 的内容块。下面是只含文本的响应的关键字段（省略了 `id`、`usage` 等字段）：

```json theme={null}
{
  "type": "message",
  "role": "assistant",
  "content": [
    {"type": "text", "text": "连接成功"}
  ]
}
```

常见的内容块类型：

| `type` | 读取的字段 | 含义 |
| - | - | - |
| `text` | `text` | 给用户看的文本回复 |
| `thinking` | `thinking` | 模型的思考过程，不是最终答案 |
| `tool_use` | `id`、`name`、`input` | 模型请求调用工具，见[工具调用](#工具调用) |

同一条回复可能包含多个内容块，第一个块也可能是 `thinking` 或 `tool_use`，所以不要直接读取 `content[0].text`。

* 遍历 `content[]` 并按 `type` 处理；
* 需要完整文本时，把所有 `text` 块按顺序拼接。

cURL 响应保存为 `message.json`（在命令末尾加 `-o message.json`）后，可以用 jq 提取文本：

```bash theme={null}
jq -r '.content[] | select(.type == "text") | .text' message.json
```

多轮对话时，把模型上一轮返回的完整 `content` 作为一条 `assistant` 消息放回 `messages`，再追加新的 `user` 消息。

## 流式输出

在请求体中加入 `"stream": true`，响应改为 SSE 事件流。事件依次是：

1. `message_start`；
2. 每个内容块的 `content_block_start` / `content_block_delta` / `content_block_stop`；
3. `message_delta`；
4. 最后以 `message_stop` 结束。

中间可能夹有 `ping`。文本增量在 `content_block_delta` 事件里：

* `delta.type` 为 `text_delta`；
* 新增文本在 `delta.text`。

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl --fail-with-body --max-time 120 -N \
      "https://api.laozhang.ai/v1/messages" \
      -H "Authorization: Bearer $LAOZHANG_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{
        "model": "glm-5.2",
        "max_tokens": 1024,
        "stream": true,
        "messages": [
          {"role": "user", "content": "用三句话介绍一下你自己"}
        ]
      }'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os
    from anthropic import Anthropic

    client = Anthropic(
        api_key=os.environ["LAOZHANG_API_KEY"],
        base_url="https://api.laozhang.ai",
        timeout=120.0,
        max_retries=0,
    )
    stream = client.messages.create(
        model="glm-5.2",
        max_tokens=1024,
        messages=[{"role": "user", "content": "用三句话介绍一下你自己"}],
        stream=True,
    )
    for event in stream:
        if event.type == "content_block_delta" and event.delta.type == "text_delta":
            print(event.delta.text, end="", flush=True)
        elif event.type == "message_stop":
            print("\n[回复结束]")
    ```
  </Tab>
</Tabs>

cURL 的 `-N` 关闭输出缓冲。文本事件与结束事件的格式如下：

```text theme={null}
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}

event: message_stop
data: {"type":"message_stop"}
```

收到 `message_stop` 才表示这条回复完整结束；在此之前连接断开，已收到的文本不完整。

## 工具调用

在请求中用 `tools` 声明函数的名称、说明和 `input_schema`。模型需要调用函数时，会在 `content[]` 中返回 `tool_use` 块。网关不会替你执行这些函数，由业务程序处理：

1. 读取 `tool_use` 块的 `name` 和 `input`，自己执行函数；
2. 把结果放进 `tool_result` 块发回，`tool_use_id` 填对应 `tool_use` 块的 `id`。

下面的示例声明了一个查询天气的函数，把本地执行结果回传给模型，直到模型给出文本答案：

```python theme={null}
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["LAOZHANG_API_KEY"],
    base_url="https://api.laozhang.ai",
    timeout=120.0,
    max_retries=0,
)
tools = [{
    "name": "get_weather",
    "description": "查询指定城市的当前天气",
    "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string", "description": "城市名"}},
        "required": ["city"],
    },
}]


def get_weather(city):
    # 替换为你的业务逻辑，例如调用天气服务
    return f"{city}：多云，22°C"


messages = [{"role": "user", "content": "上海现在天气怎么样？"}]
for _ in range(5):
    message = client.messages.create(
        model="glm-5.2",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    tool_uses = [block for block in message.content if block.type == "tool_use"]
    if not tool_uses:
        break
    messages.append({"role": "assistant", "content": message.content})
    results = []
    for block in tool_uses:
        if block.name == "get_weather":
            output = get_weather(**block.input)
        else:
            output = f"未知工具：{block.name}"
        results.append({
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": output,
        })
    messages.append({"role": "user", "content": results})

print("".join(block.text for block in message.content if block.type == "text"))
```

回传结果时，`assistant` 消息要原样包含上一轮返回的完整 `content`，并在后续请求中继续携带同样的 `tools`。

Anthropic 托管的服务器工具（`web_search_*`、`code_execution_*` 等）不会在网关执行，只会作为普通的 `tool_use` 块返回。

需要联网搜索或运行代码时，由业务程序自己实现，并按上面的方式回传 `tool_result`。

## 在 Claude Code 中使用

Claude Code 同样使用 Anthropic Messages 格式：

* `ANTHROPIC_BASE_URL` 设为 `https://api.laozhang.ai`（域名根，不加 `/v1`）；
* 模型选择「兼容端点」包含 Anthropic Messages 的模型 ID。价格配置中 `glm-5.2` 同时开放于 `default` 与 `claude_code` 分组，各分组的用途与权限以控制台说明为准。

完整的 `~/.claude/settings.json` 示例见 [Claude Code 配置与 400 ValidationException 排查](/faq/claude-code-aws-400-validation-error)。

## 常见错误

* **401**：API Key 无效或认证头格式不对。cURL 使用 `Authorization: Bearer` 加老张API密钥；不要使用控制台账号的 AccessToken。
* **400，提示缺少 `max_tokens`**：Messages 协议要求每个请求都带 `max_tokens`，在请求体中补上即可。
* **SDK 请求发到了 `/v1/v1/messages`**：Anthropic SDK 的 `base_url` 多写了 `/v1`。改为 `https://api.laozhang.ai`，由 SDK 拼接路径。
* **读取 `content[0].text` 报错或为空**：第一个内容块可能是 `thinking` 或 `tool_use`，按 `type` 遍历读取。
* **回复在中途截断**：输出达到了 `max_tokens` 上限，调大该值后重试。
* **声明了 `web_search` 等服务器工具却没有结果**：网关不执行服务器工具，由业务程序执行后回传 `tool_result`。
* **403 或模型不可用**：确认模型 ID 完整、其「兼容端点」包含 Anthropic Messages，且 API Key 所在令牌分组有该模型权限，排查步骤见[模型可用性与权限](/faq/model-availability)。
* **5xx 或超时**：先在[调用日志](/faq/call-logs)确认请求状态，再决定是否重试。

## 相关文档

* [Anthropic 官方 Messages API 参考](https://platform.claude.com/docs/zh-CN/api/messages/create)
* [Anthropic 官方流式输出说明](https://platform.claude.com/docs/zh-CN/build-with-claude/streaming)
* [Anthropic 官方工具调用说明](https://platform.claude.com/docs/zh-CN/agents-and-tools/tool-use/overview)
* [模型与价格总表](/models)
* [OpenAI 协议](/api-reference/chat-completions)
* [Gemini 协议](/api-reference/gemini)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.