# Anthropic 兼容 API

使用 Messages 请求格式和 Anthropic SDK，理解内容块、工具与 Thinking 的转换边界。

## 接口定位 [#接口定位]

Messages 接口接受 Anthropic 格式请求，内部转换成 Chat Completions，再把返回结果转换为 Messages 内容块。协议格式与模型厂商是不同概念：`model` 必须填 GFW 模型 ID，并不要求名称是 Claude 型号。

本文使用 `deepseek-v4-pro` 演示基础文本调用，模型可用性与授权范围请查看 [模型库](/models)。示例不是官方 Anthropic 服务的能力承诺，也不是实际请求记录。

## 端点与 SDK 地址 [#端点与-sdk-地址]

| 项目 | 值 |
| --- | --- |
| 首选路径 | `POST https://api.gfw.net/v1/messages` |
| 兼容路径 | `POST https://api.gfw.net/anthropic/v1/messages` |
| Anthropic SDK `base_url` | `https://api.gfw.net` |
| 鉴权 | `x-api-key: $GFW_API_KEY`，也支持 Bearer API Key |
| 请求头 | `Content-Type: application/json`、`anthropic-version: 2023-06-01` |

Anthropic SDK 会补上 `/v1/messages`，因此不要把 `/v1` 再写进它的 `base_url`。使用同一个 GFW API Key，不要用控制台登录 Token。

## 请求参数与内容块 [#请求参数与内容块]

| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | GFW 模型 ID |
| `max_tokens` | integer | 是 | 必须大于 0；输出预算应符合模型限制 |
| `messages` | array | 常规对话是 | 带 `role` 与 `content` 的历史消息，主要使用 `user`、`assistant` |
| `system` | string / array | 否 | 顶层系统提示；数组中的文本被连接成 system 消息 |
| `temperature`、`top_p`、`top_k` | number / integer | 否 | 透传兼容参数；`top_k` 仅部分上游支持 |
| `stop_sequences` | array of strings | 否 | 转成 Chat Completions 的 `stop` |
| `stream` | boolean | 否 | `true` 返回命名 SSE 事件 |
| `tools` | array | 否 | `name`、`description`、`input_schema` 转成 function 定义，模型需支持工具调用 |
| `thinking` | object | 否 | `type=enabled` 时进入 Thinking 兼容转换，详见 [推理模型](/docs/reasoning) |

`content` 可以是文本字符串或内容块数组。转换器处理 `text`、`image`、`tool_use`、`tool_result`；不要默认文档块、服务器工具或其他类型都能被识别。视觉输入使用 `source.type=base64`、`media_type` 和 `data`；外部 URL 在转换后会被图片校验拒绝。

当前工具转换处理 `tools`，但未实现完整的 Anthropic `tool_choice` 映射。若需要精确选择工具，优先使用 [Chat Completions](/docs/tool-calls)，不要把原生参数直接当作已支持。

## 完整调用示例 [#完整调用示例]

设置 `GFW_API_KEY`；Python 示例依赖 `anthropic` 包。`system` 在顶层设置，不混入 `messages` 的 role。



**cURL**


```bash
curl --fail-with-body --silent --show-error \
  --max-time 120 \
  https://api.gfw.net/v1/messages \
  -H "x-api-key: ${GFW_API_KEY:?请先设置 GFW_API_KEY}" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  --data '{
    "model": "deepseek-v4-pro",
    "max_tokens": 512,
    "system": "你是一名后端工程师，用简洁的中文回答。",
    "messages": [{"role": "user", "content": "什么时候不应自动重试 POST 请求？"}],
    "stream": false
  }'
```



**Python**


```python
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["GFW_API_KEY"],
    base_url="https://api.gfw.net",
    timeout=120.0,
    max_retries=0,
)
response = client.messages.create(
    model="deepseek-v4-pro",
    max_tokens=512,
    system="你是一名后端工程师，用简洁的中文回答。",
    messages=[{"role": "user", "content": "什么时候不应自动重试 POST 请求？"}],
    stream=False,
)
for block in response.content:
    if block.type == "text":
        print(block.text)
print("stop_reason:", response.stop_reason)
print("usage:", response.usage)
```




## 响应字段 [#响应字段]

以下为结构示意，内容和用量并非实测：

```json
{
  "id": "msg_chatcmpl_example",
  "type": "message",
  "role": "assistant",
  "model": "deepseek-v4-pro",
  "content": [{"type": "text", "text": "当请求可能已经产生副作用且无法去重时，不应盲目重试。"}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 32, "output_tokens": 25, "cache_creation_input_tokens": 0, "cache_read_input_tokens": 0}
}
```

| 字段 | 说明 |
| --- | --- |
| `content[]` | 按类型读取，可能包含 `text`、`thinking`、`tool_use`，不保证第一块就是文本 |
| `stop_reason=end_turn` | 普通结束 |
| `stop_reason=max_tokens` | 达到输出限制，应检查结果是否截断 |
| `stop_reason=tool_use` | 应用需处理工具请求并用 `tool_result` 回传 |
| `usage` | 转换后的 Token 用量；缓存创建字段在当前非流式桥接中为 0，不代表完整缓存功能已经实现 |

流式输出使用 `message_start`、`content_block_start`、`content_block_delta`、`content_block_stop`、`message_delta`、`message_stop`。工具流转换为基础实现，不宜依赖复杂并行工具场景；生产工具循环建议先使用非流式路径。

## 兼容边界与相关文档 [#兼容边界与相关文档]

- Thinking 块来自上游 `reasoning_content` 的转换，不保证存在签名或完整原生 Extended Thinking 语义。若上游没有最终文本而只有推理文本，当前非流式转换可能将其放入 `text`；应用必须知道这一差异。
- 工具执行发生在你的应用中，网关不会执行工具。保留 `tool_use.id`，回传时作为 `tool_result.tool_use_id`。
- 缓存控制、文档输入、服务器工具和 Token 计数端点等未在当前契约中完整确认，本文不提供对应路径或通用支持承诺。
- Anthropic 错误通常为 `type=error` 加 `error.type`、`error.message`；和 OpenAI 错误、平台业务码不能混用。

相关文档：[流式输出](/docs/streaming)、[工具调用](/docs/tool-calls)、[推理模型](/docs/reasoning)、[Claude Code](/docs/claude-code)、[错误码与重试](/docs/errors)。