Claude 对话 API

无界模型云提供 Claude 系列对话模型，覆盖最新一代 Opus、Sonnet、Haiku。可用两种形态接入：Anthropic 原生 Messages 接口与 OpenAI 兼容接口，两套接口共享同一账户、同一 Key 和同一计费体系。

概览

• Anthropic 原生 Messages：POST https://api.tos.run/v1/messages，适合已经使用 Anthropic SDK 或 Claude 生态工具链的应用，可直接复用 messages、system、tools、thinking、cache_control 等原生能力。
• OpenAI 兼容：POST https://api.tos.run/v1/chat/completions，适合已有 OpenAI 兼容客户端的应用，零改造切换到 Claude。
• 模型族包含 Claude Opus、Sonnet、Haiku 三档：Opus 面向复杂编程与深度推理，Sonnet 面向通用任务与日常编码，Haiku 面向高并发与快速响应。

鉴权与 Base

API 数据面 Base 为 https://api.tos.run（浏览器控制台是 https://ai.tos.run，不要用作 API Base）。两种形态都用 Authorization: Bearer 鉴权头：

原生 Messages 请求还需带 anthropic-version: 2023-06-01 与 content-type: application/json。在控制台创建 API Key 后，将其存入环境变量 AI_TOS_API_KEY 再发起调用。

Messages 调用

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

curl https://api.tos.run/v1/messages \
  -H "Authorization: Bearer $AI_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, requests

resp = requests.post(
    "https://api.tos.run/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['AI_TOS_API_KEY']}",
        "anthropic-version": "2023-06-01",
        "content-type": "application/json",
    },
    json={
        "model": "claude-sonnet-4-x",
        "max_tokens": 1024,
        "system": "你是一个简洁的中文助手。",
        "messages": [
            {"role": "user", "content": "用三句话介绍一下你自己。"}
        ],
    },
)
print(resp.json())

const resp = await fetch("https://api.tos.run/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AI_TOS_API_KEY}`,
    "anthropic-version": "2023-06-01",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-x",
    max_tokens: 1024,
    system: "你是一个简洁的中文助手。",
    messages: [{ role: "user", content: "用三句话介绍一下你自己。" }],
  }),
});
console.log(await resp.json());

OpenAI 兼容调用

如果已有 OpenAI 兼容客户端，只需切换 Base、Key 和模型 ID 即可使用 Claude。system 提示在该形态下作为 role: "system" 的消息传入。

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

参数

以下参数适用于 Anthropic 原生 Messages 接口。

OpenAI 兼容接口使用 OpenAI 标准字段（messages、max_tokens、temperature、top_p、stop、stream、tools、tool_choice 等）。

流式

设置 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 $AI_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 $AI_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（非缓存输入）、cached_input_tokens（缓存命中输入）、output_tokens 分别计费。
• 缓存命中输入按较低价格计费；有显式缓存价格时使用显式行，否则按同档输入价格的较低折扣计费。
• 上下文档位按本次请求输入 token 判断：≤128k、≤256k、>256k，不同档位单价不同。
• 推理（扩展思考）、工具结果、检索上下文最终都会体现在输入或输出 token 中。

接入建议

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