POST /v1/messages

接口用途

Anthropic Messages API 兼容入口，也是 Claude SDK / Claude Code 最推荐的接入方式之一。

当 API Key 绑定的是 OpenAI 分组时，这条路由会自动切换到 OpenAI 兼容实现；否则进入 Anthropic / Claude 兼容实现。

请求路径

POST /v1/messages

完整地址示例：

https://your-domain/api/v1/v1/messages

认证方式

• Authorization: Bearer <API_KEY>，推荐
• x-api-key: <API_KEY>

路由别名

无根路径别名。

适用平台

• Anthropic / Claude 分组：原生 Claude 兼容实现
• OpenAI 分组：自动转到 OpenAI 兼容 Messages 实现
• Antigravity：在 /antigravity/v1/messages 下有专用入口

上游官方规范

• Anthropic Messages API

本项目支持说明

• 自动按分组平台分流
• 支持流式与非流式
• 会做 API Key、用户、IP、余额 / 订阅、并发和内容审核检查
• 会根据分组配置做模型映射与限制
• 对 Claude Code 客户端有额外上下文识别与版本检查逻辑

参数说明

常用上游标准字段

参数	类型	必填	说明
model	string	是	上游模型名；本项目也会用它做分组内模型路由与限制判断
messages	array	是	标准 Anthropic 消息数组
max_tokens	number	是	最大输出 token 数
stream	boolean	否	是否启用流式响应
system	`string	array`	否
tools	array	否	工具定义
metadata	object	否	上游兼容元数据

完整字段请参考 Anthropic 官方规范。

KToken 差异与限制

字段 / 行为	说明
model	不能为空；缺失时返回 400 invalid_request_error
空请求体	直接返回 400 Request body is empty
非法 JSON	返回 400 Failed to parse request body
stream=true	会影响并发占位与流式输出链路
分组平台	由 API Key 当前分组决定最终走 OpenAI 还是 Anthropic 实现

响应说明

成功时返回 Anthropic Messages 响应；流式时返回 SSE。

常见成功响应示例：

{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-20250514",
  "content": [
    {
      "type": "text",
      "text": "你好，我可以帮你做什么？"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 18
  }
}

错误响应

典型错误：

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "model is required"
  }
}

示例请求

curl https://your-domain/api/v1/v1/messages \
  -H "Authorization: Bearer sk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 512,
    "messages": [
      { "role": "user", "content": "请介绍一下你自己" }
    ]
  }'

注意事项

• 这是 Claude 客户端最稳定的接入入口之一
• 如果你实际绑定的是 OpenAI 分组，不要假设一定会落到 Anthropic 上游
• 如果只允许 Claude Code 客户端的分组使用 /v1/chat/completions，代码会直接拒绝