Anthropic 兼容接口

Mozia API 提供 Anthropic Messages 格式的文本接口。支持该格式的应用可以替换基础地址、API Key 和模型 ID，调用平台上支持相应能力的模型。Claude Code 的完整配置见接入指南 → Claude Code。

协议兼容不代表每个模型都具备 Anthropic 的全部能力。工具调用、图片输入、推理、提示缓存及其他高级参数的支持范围，取决于所选模型和上游服务。

接口与鉴权

项目	值
基础地址	`https://mzsjai.com`
创建消息	`POST /v1/messages`
查询可用模型	`GET /v1/models`，返回 OpenAI 格式模型列表
请求类型	`Content-Type: application/json`
协议版本头	`anthropic-version: 2023-06-01`

支持下面两种认证方式，选择一种即可：

Authorization: Bearer <YOUR_API_KEY>

或使用 Anthropic SDK 常用的请求头：

x-api-key: <YOUR_API_KEY>

不要同时发送两个不同的密钥。Claude Code 使用 ANTHROPIC_AUTH_TOKEN 时发送 Bearer 认证；Anthropic SDK 的 api_key 通常发送 x-api-key。

以下示例使用自己的 Matrix API Key。model 必须填写平台公开的完整 ID，不要将上游内部名称或 Claude 的 sonnet、opus 别名直接作为平台模型 ID。

export MOZIA_API_KEY='<YOUR_API_KEY>'

创建消息

curl --fail-with-body \
  'https://mzsjai.com/v1/messages' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  --data-binary @- <<'JSON'
{
  "model": "deepseek/deepseek-v4-flash",
  "max_tokens": 1024,
  "system": "请使用简洁的中文回答。",
  "messages": [
    {"role": "user", "content": "用三句话解释什么是向量数据库。"}
  ]
}
JSON

常用参数

字段	类型	必填	说明
`model`	string	是	当前 API Key 可用的完整模型 ID
`max_tokens`	integer	是	正整数，限制本次输出 Token 数；不是上下文窗口大小
`messages`	array	是	对话历史，使用 `user`、`assistant` 角色
`system`	string 或内容块数组	否	系统提示；放在顶层，不在 `messages` 中插入 system 角色
`stream`	boolean	否	`true` 使用 SSE，默认 `false`
`temperature`	number	否	采样温度，范围由模型决定
`top_p`	number	否	核采样参数，通常不与 temperature 同时调整
`top_k`	integer	否	仅对支持该采样参数的模型生效
`stop_sequences`	string 数组	否	自定义停止序列
`tools`	array	否	工具名称、说明和 input_schema
`tool_choice`	object	否	例如 `{"type":"auto"}`，具体策略支持依赖模型
`thinking`	object	否	推理配置，依赖模型能力
`output_config`	object	否	如 effort 等输出配置，依赖模型与转换支持

content 可以是字符串，也可以是内容块数组，例如：

{
  "role": "user",
  "content": [{"type": "text", "text": "你好"}]
}

多轮对话需要在每次请求中携带前面的 user 和 assistant 消息。接口不会仅凭上一次响应 ID 自动恢复历史。

非流式响应

下面是结构示例，文本与用量为演示值：

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "deepseek/deepseek-v4-flash",
  "content": [{"type": "text", "text": "向量数据库用于存储和检索向量。"}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 24, "output_tokens": 18}
}

从 content 中读取 type=text 的内容块，不要使用 OpenAI 的 choices[0].message.content。部分模型还会返回 thinking 或 tool_use 块，应按类型处理；响应的 model 标识可能因上游映射而不同。

`stop_reason`	含义
`end_turn`	模型完成本轮回答
`max_tokens`	达到输出上限，回答可能不完整
`tool_use`	模型要求调用工具，需要回传工具结果
`stop_sequence`	命中自定义停止序列

客户端应兼容其他结束原因。usage 中的缓存明细仅在服务返回时可用，不应把缺失字段当作已经命中缓存。

流式响应

请求中设置 stream: true，客户端按 Server-Sent Events 解析：

curl --fail-with-body -N --no-buffer \
  'https://mzsjai.com/v1/messages' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  --data-binary @- <<'JSON'
{
  "model": "deepseek/deepseek-v4-flash",
  "max_tokens": 1024,
  "stream": true,
  "messages": [{"role": "user", "content": "介绍一下杭州。"}]
}
JSON

常见事件顺序如下，一个响应可以有多个内容块：

message_start
content_block_start
content_block_delta（可多次）
content_block_stop
message_delta
message_stop

文本增量通常位于 content_block_delta 的 delta.text，增量类型为 text_delta。
工具参数使用 input_json_delta 时，先按内容块 index 拼接 partial_json，到该块结束后再解析 JSON，不要逐片段解析。
结束原因与用量更新见 message_delta；收到 message_stop 才表示消息正常结束，不能只等 OpenAI 格式的 [DONE]。
处理可能出现的 ping、error 和新的事件类型。HTTP 200 不保证后续流一定完成；流中错误或提前断开也需要处理。

事件结构参考 Anthropic 流式消息说明。

工具调用与结果回传

在请求中声明工具：

{
  "model": "deepseek/deepseek-v4-flash",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "查询订单 DEMO-001 的状态。"}],
  "tools": [
    {
      "name": "get_order_status",
      "description": "根据订单编号查询订单状态",
      "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }
  ],
  "tool_choice": {"type": "auto"}
}

如果模型返回 stop_reason: "tool_use"，content 中会包含类似内容：

{
  "type": "tool_use",
  "id": "toolu_example",
  "name": "get_order_status",
  "input": {"order_id": "DEMO-001"}
}

应用执行工具后，将原始 assistant content 完整加入历史，再紧接着添加 user 消息中的 tool_result。以下只演示一个工具块和虚构订单结果；实际使用返回的 ID 与真实执行结果：

{
  "model": "deepseek/deepseek-v4-flash",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "查询订单 DEMO-001 的状态。"},
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "id": "toolu_example",
          "name": "get_order_status",
          "input": {"order_id": "DEMO-001"}
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_example",
          "content": "{\"order_id\":\"DEMO-001\",\"status\":\"shipped\"}"
        }
      ]
    }
  ],
  "tools": [
    {
      "name": "get_order_status",
      "description": "根据订单编号查询订单状态",
      "input_schema": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }
  ]
}

tool_use_id 必须对应此前模型返回的 id。一次出现多个工具调用时，回传每一个工具的结果。工具执行失败可以在 tool_result 中设置 is_error: true，并提供简短错误说明。

平台负责转发工具定义和结果，不会替应用执行数据库查询、文件读取或其他本地操作。应用需要自行验证工具参数与执行权限。

使用 Anthropic Python SDK

安装 SDK：

python -m pip install anthropic

基础地址使用域名根路径，SDK 自动拼接 /v1/messages：

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["MOZIA_API_KEY"],
    base_url="https://mzsjai.com",
)

message = client.messages.create(
    model="deepseek/deepseek-v4-flash",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话解释 HTTP。"}],
)

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

需要流式输出时，将上面的 create 调用改为：

with client.messages.stream(
    model="deepseek/deepseek-v4-flash",
    max_tokens=1024,
    messages=[{"role": "user", "content": "介绍一下杭州。"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

推理与兼容范围

支持相应能力的模型可以接收 thinking 或 output_config.effort，例如自适应推理的配置片段：

{
  "thinking": {"type": "adaptive"},
  "output_config": {"effort": "max"}
}

这不是完整请求，需要与 model、messages、max_tokens 一起使用。是否支持 adaptive、effort 的可用值以及转换后的实际推理强度，取决于模型；请求被接受不代表所有模型采用相同推理预算。

回传多轮历史时保留模型返回的 thinking 块及其 signature，不自行编造签名或把推理内容改成普通文本。本页的工具示例省略了没有出现在示例响应中的 thinking 块。

本文覆盖 Messages 文本、流式响应和工具调用。不要据此假设所有 Anthropic API 路径、beta 功能、文件、批处理、服务端工具、提示缓存或 token counting 都可用。图片输入也需要额外确认模型与渠道支持。

错误处理

Messages 错误常见结构如下；认证中间件或上游也可能返回不同字段，调用方应同时检查 HTTP 状态码、error 和请求 ID：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Error description"
  }
}

状态码	排查方向
`400`	请求结构、参数、历史消息或模型能力不匹配
`401`	API Key 缺失、无效或失效
`403`	模型权限、Key 限制或上游拒绝当前请求；不一定是密钥错误
`404`	检查接口地址与完整模型 ID
`429`	根据错误信息检查额度与频率限制，必要时有限退避重试
`500/502/503/504`	平台或上游异常；保留请求 ID，必要时联系平台

不要无限重试参数或权限错误。流式请求还需处理事件中的 error；故障排查时提供发生时间、模型、状态码及请求 ID，不要提供完整 API Key。

接口与鉴权​

创建消息​

常用参数​

非流式响应​

流式响应​

工具调用与结果回传​

使用 Anthropic Python SDK​

推理与兼容范围​

错误处理​