Messages 对话 API（Anthropic 原生）

无界模型云提供 Anthropic 原生 Messages 协议接口 POST /v1/messages，覆盖最新一代 Claude Opus、Sonnet、Haiku。已经使用 Anthropic SDK 或 Claude 生态工具链（Claude Code、Claude SDK 等）的应用可直接复用 messages、system、tools、thinking、cache_control 等原生能力。

私有化部署 API 完全一致，仅需替换 Base 域名 → 企业私有化部署。

如需 OpenAI 兼容形态调用 Claude，见 Chat Completions 对话 API，两套接口共享同一账户、同一 Key 与同一计费体系。

概览

• 端点：POST https://api.tos.run/v1/messages（Anthropic 原生 Messages 协议）
• Base：https://api.tos.run（API 数据面；浏览器控制台是 https://ai.tos.run，不要用作 API Base）
• 模型族：Claude Opus（复杂编程与深度推理）、Sonnet（通用任务与日常编码）、Haiku（高并发与快速响应）

鉴权与 Base

API Base 为 https://api.tos.run。鉴权头：

Authorization: Bearer gk_xxxxxxxxxxxxxxxx
anthropic-version: 2023-06-01
content-type: application/json

• 鉴权头为 Authorization: Bearer <gk_...>（OpenAI 与 Anthropic 两条路径都用 Bearer），API Key 以 gk_ 开头，在控制台创建。
• 网关不接受入站 x-api-key——只读 Authorization 头，且必须带 Bearer 前缀，否则返回 401。
• 原生 Messages 请求还需带 anthropic-version: 2023-06-01。

生产环境请把 Key 放在服务端，不要暴露到浏览器。

provider 选择

/v1/messages 缺省 provider 默认为 anthropic（这是 Anthropic 协议路径，Claude Code / Claude SDK 等客户端通过 ANTHROPIC_BASE_URL 接入时发送的是无 provider 字段的 Anthropic-shape 请求）。如需指定其他号源，可用 X-Provider 头或 body.provider 覆盖（二者优先于默认值）。

Messages 调用

max_tokens 为必填项，用于限制单次响应的最大输出 token。

curl https://api.tos.run/v1/messages \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-x",
    "max_tokens": 1024,
    "system": "你是一个简洁的中文助手。",
    "messages": [
      { "role": "user", "content": "用三句话介绍一下你自己。" }
    ]
  }'

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://api.tos.run",
    auth_token=os.environ["TOS_API_KEY"],  # → Authorization: Bearer gk_...
)

msg = client.messages.create(
    model="claude-sonnet-4-x",
    max_tokens=1024,
    system="你是一个简洁的中文助手。",
    messages=[{"role": "user", "content": "用三句话介绍一下你自己。"}],
)
print(msg.content[0].text)

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

const client = new Anthropic({
  baseURL: "https://api.tos.run",
  authToken: process.env.TOS_API_KEY, // → Authorization: Bearer gk_...
});

const msg = await client.messages.create({
  model: "claude-sonnet-4-x",
  max_tokens: 1024,
  system: "你是一个简洁的中文助手。",
  messages: [{ role: "user", content: "用三句话介绍一下你自己。" }],
});
console.log(msg.content[0].text);

参数

内容块上的 cache_control 用于命中提示缓存。

anthropic-beta 头

网关在客户端未自带 anthropic-beta 头时，会默认注入：

anthropic-beta: oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27

如果客户端自带 anthropic-beta（如 Claude Code CLI 自行协商的 beta 矩阵），网关会原样保留客户端的取值，不做覆盖。

流式

设置 stream: true 后，响应以 Server-Sent Events（SSE）逐块返回。主要事件类型：

• message_start：消息开始，携带初始的 message 元信息。
• content_block_delta：内容增量，文本片段在 delta.text 中。
• message_delta：消息级增量，携带 stop_reason 与累计 usage。
• message_stop：消息结束。

curl https://api.tos.run/v1/messages \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-x",
    "max_tokens": 1024,
    "stream": true,
    "messages": [
      { "role": "user", "content": "写一首关于云的短诗。" }
    ]
  }'

工具调用

通过 tools 声明可调用的函数，模型在需要时返回 tool_use 内容块。应用执行工具后，把结果以 tool_result 块回填到下一轮 messages 中，模型据此给出最终回答。

curl https://api.tos.run/v1/messages \
  -H "Authorization: Bearer $TOS_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-x",
    "max_tokens": 1024,
    "tools": [
      {
        "name": "get_weather",
        "description": "查询指定城市的天气",
        "input_schema": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "城市名称" }
          },
          "required": ["city"]
        }
      }
    ],
    "messages": [
      { "role": "user", "content": "合肥今天天气怎么样？" }
    ]
  }'

模型返回的 tool_use 块包含 id、name 和 input。执行工具后，按如下结构回填结果并再次请求：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_xxx",
      "content": "晴，26°C"
    }
  ]
}

提示缓存

对系统提示、长文档等稳定且重复出现的内容，可在内容块上添加 cache_control 命中提示缓存，降低输入成本并提升响应速度。

{
  "system": [
    {
      "type": "text",
      "text": "（大段固定的业务背景与规则……）",
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

缓存写入会产生 cache_creation_input_tokens，后续命中的部分计入 cache_read_input_tokens，缓存命中输入按更低的价格计费。

响应与用量

原生 Messages 响应的关键字段：

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "content": [
    { "type": "text", "text": "你好，我是一个中文助手……" }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 24,
    "output_tokens": 38,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

计费

Claude 系列遵循无界模型云的 LLM 计费规则，按 token 计量，单位为 1M token：

• 按 input_tokens（非缓存输入）、缓存命中输入、output_tokens 分别计费。
• 缓存命中输入按较低价格计费；有显式缓存价格时使用显式行，否则按同档输入价格的较低折扣计费。
• 推理（扩展思考）、工具结果、检索上下文最终都会体现在输入或输出 token 中。

接入建议

• 生产环境把 API Key 放在服务端，不要暴露到浏览器或客户端。
• 给不同应用使用不同 Key，便于审计、限额和停用。
• 先按真实业务样本估算 token，再设置额度与告警；工具调用、检索上下文与思考 token 都要纳入预算。
• 把模型 ID 作为配置项管理，跟随控制台更新平滑切换到新版本。

相关页面

• Chat Completions 对话 API
• Responses API（OpenAI 兼容）
• 鉴权