Claude 协议：Messages

通过 POST /v1/messages 使用 Anthropic Messages 格式调用 WisGate 模型。本文用 deepseek-v4-flash 演示协议接入；模型仍是请求指定的 DeepSeek 路由，不会因为使用 Claude 协议而变成 Claude 模型。

后端既有原生 Claude 协议路径，也有 Claude 与 OpenAI Chat 之间的转换路径。DeepSeek 专用渠道会发送到上游 /anthropic/v1/messages；不同渠道对高级字段的保留能力不同。

接口与鉴权

项目	值
地址	https://api.wisgate.cn/v1/messages
方法	POST
内容类型	application/json
推荐鉴权头	x-api-key: YOUR_API_KEY
兼容鉴权头	Authorization: Bearer YOUR_API_KEY
协议版本头	anthropic-version: 2023-06-01
Anthropic SDK base URL	https://api.wisgate.cn，不手工追加 /v1

两种鉴权头选择一种；入站中间件在 Messages 路径会优先用非空 x-api-key。请使用 WisGate API Key。

基本调用

curl --fail-with-body https://api.wisgate.cn/v1/messages \
  -H "x-api-key: $WISGATE_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "deepseek-v4-flash",
    "max_tokens": 1024,
    "system": "请用简洁的中文回答。",
    "messages": [{"role":"user","content":"解释什么是 API。"}]
  }'

响应结构示例：

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "deepseek-v4-flash",
  "content": [{"type":"text","text":"API 是程序之间交换信息的接口。"}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens":24,"output_tokens":16}
}

遍历 content，仅将 type=text 的 text 拼接为普通正文。数组也可能包含工具或 thinking 块，不能假定全部是文本。不同上游可能返回额外字段。

请求参数

参数	类型	要求与含义
model	string	必填，WisGate 模型名
messages	array	必填且非空，消息 role 使用 user / assistant
messages[].content	string / array	文本或内容块
max_tokens	integer	按标准调用显式提供正整数；不要依赖渠道默认补值
system	string / array	顶层系统指令，不要在 messages 中添加 system role
stream	boolean	是否返回 SSE
temperature、top_p	number	可选采样控制，具体支持依赖模型
top_k	integer	原生协议字段；OpenAI 桥接不保证保留
stop_sequences	string[]	停止序列
tools	array	客户端工具定义，使用 input_schema
tool_choice	object	工具选择；原生渠道与桥接渠道支持不同
thinking	object	模型相关，不应套用 Claude 的预算范围到 DeepSeek
metadata	object	可选扩展；跨协议转换不保证保留

格式参考 Anthropic Messages。网关可解析字段不代表模型接受全部参数。

多轮消息

下一次请求发送完整历史，并继续提供所需 system：

{
  "model": "deepseek-v4-flash",
  "max_tokens": 1024,
  "system": "请用简洁的中文回答。",
  "messages": [
    {"role":"user","content":"解释什么是 API。"},
    {"role":"assistant","content":[{"type":"text","text":"API 是程序之间交换信息的接口。"}]},
    {"role":"user","content":"再给一个例子。"}
  ]
}

流式调用

curl --fail-with-body -N https://api.wisgate.cn/v1/messages \
  -H "x-api-key: $WISGATE_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'Content-Type: application/json' \
  -d '{"model":"deepseek-v4-flash","max_tokens":1024,"messages":[{"role":"user","content":"用三句话介绍杭州。"}],"stream":true}'

正常流的基本生命周期：message_start → 多组 content_block_start/delta/stop → message_delta → message_stop。也可能出现 ping、error；不要使用 Chat 的 [DONE] 作为唯一结束标志。

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"杭州"}}

text_delta.text 用于正文；input_json_delta.partial_json 用于按 index 拼接工具参数，块结束后解析。message_delta.usage 的输出用量按累计值更新，不要逐事件相加。协议事件参考 Anthropic 流式文档。

工具声明与回传

第一轮请求示例：

{
  "model": "deepseek-v4-flash",
  "max_tokens": 1024,
  "messages": [{"role":"user","content":"查询杭州天气。"}],
  "tools": [{
    "name": "get_weather",
    "description": "查询城市天气",
    "input_schema": {
      "type": "object",
      "properties": {"city":{"type":"string"}},
      "required": ["city"]
    }
  }]
}

若 stop_reason=tool_use，从 assistant 的 content 读取 tool_use 块，校验后执行函数。下一轮把该 assistant 内容原样保留，再以 user 消息发送 tool_result：

{
  "model": "deepseek-v4-flash",
  "max_tokens": 1024,
  "messages": [
    {"role":"user","content":"查询杭州天气。"},
    {"role":"assistant","content":[{"type":"tool_use","id":"toolu_example","name":"get_weather","input":{"city":"杭州"}}]},
    {"role":"user","content":[{"type":"tool_result","tool_use_id":"toolu_example","content":"{\"temperature_c\":24}"}]}
  ]
}

天气为示意数据。真实返回若包含文本、thinking 或签名块，应遵循目标上游要求保留完整内容。多个 tool_use 需要分别返回匹配 ID 的结果；工具不是网关代为执行。

Python 与 TypeScript SDK

Python（安装 anthropic）：

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["WISGATE_API_KEY"], base_url="https://api.wisgate.cn")
message = client.messages.create(
    model="deepseek-v4-flash",
    max_tokens=1024,
    messages=[{"role":"user","content":"解释什么是 API。"}],
)
print("".join(block.text for block in message.content if block.type == "text"))

Node.js（安装 @anthropic-ai/sdk）：

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({ apiKey: process.env.WISGATE_API_KEY, baseURL: "https://api.wisgate.cn" });
const stream = await client.messages.create({
  model: "deepseek-v4-flash",
  max_tokens: 1024,
  messages: [{ role: "user", content: "解释什么是 API。" }],
  stream: true,
});
for await (const event of stream) {
  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
    process.stdout.write(event.delta.text);
  }
}

兼容范围与排错

情况	说明
stop_reason=end_turn	正常回复结束
stop_reason=max_tokens	达到预算，输出可能不完整
stop_reason=stop_sequence	命中停止序列
stop_reason=tool_use	进入工具往返流程
usage	主要字段为 input_tokens/output_tokens；缓存字段依赖上游，不套用 Chat 字段名
system 无效	检查是否错误地放在 messages 的 system role 中
返回 401/403	检查 WisGate Key 与模型权限
参数丢失	检查是否走 Claude→OpenAI 桥接，不能假定高级参数完全兼容

Claude→OpenAI 桥接当前映射基础消息、system、stop_sequences、函数工具和结果，但没有完整复制 tool_choice、top_k、metadata 等语义。原生路径与桥接路径不能共用“全部 Anthropic 特性可用”的承诺。

不在本页承诺范围：Messages Batches、/v1/messages/count_tokens、Claude 内置服务端工具、PDF/citations、prompt caching、computer use、beta 特性及所有图片输入形式。代码中存在部分相关字段不代表整个流程可用。

Messages 业务错误通常为 {"type":"error","error":{"type":"...","message":"..."}}；更早的鉴权或限流中间件可能返回通用网关错误。HTTP 流开始后需处理事件中的错误及异常中断。