Anthropic 兼容 API
使用 Messages 请求格式和 Anthropic SDK，理解内容块、工具与 Thinking 的转换边界。
接口定位
Messages 接口接受 Anthropic 格式请求，内部转换成 Chat Completions，再把返回结果转换为 Messages 内容块。协议格式与模型厂商是不同概念：model 必须填 GFW 模型 ID，并不要求名称是 Claude 型号。
本文使用 deepseek-v4-pro 演示基础文本调用，模型可用性与授权范围请查看 模型库。示例不是官方 Anthropic 服务的能力承诺，也不是实际请求记录。
端点与 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 兼容转换，详见 推理模型 |
content 可以是文本字符串或内容块数组。转换器处理 text、image、tool_use、tool_result；不要默认文档块、服务器工具或其他类型都能被识别。视觉输入使用 source.type=base64、media_type 和 data；外部 URL 在转换后会被图片校验拒绝。
当前工具转换处理 tools，但未实现完整的 Anthropic tool_choice 映射。若需要精确选择工具，优先使用 Chat Completions，不要把原生参数直接当作已支持。
完整调用示例
设置 GFW_API_KEY；Python 示例依赖 anthropic 包。system 在顶层设置，不混入 messages 的 role。
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
}'响应字段
以下为结构示意，内容和用量并非实测：
{
"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 错误、平台业务码不能混用。
相关文档：流式输出、工具调用、推理模型、Claude Code、错误码与重试。