工具与客户端
Claude Code 与 Claude API
选择 Claude 分组，接入原生 Messages、流式输出与工具调用。
先选择 Claude 渠道
- 在控制台 API 密钥页面新建或编辑密钥，选择 Claude 订阅渠道；如看不到该分组，请先联系管理员开通。
- 打开模型与价格查看当前模型和价格，再用这把密钥请求 /v1/models 确认权限。
- Claude 密钥与 OpenAI 密钥按分组路由；需要两类模型时分别创建对应分组的密钥。
模型权限取决于上游账号、分组白名单和当前额度。价格按输入、输出、缓存写入和缓存命中分别计算，以控制台当前展示为准。
Claude Code
先安装或更新官方 Claude Code。Opus 5.5 需要 2.1.280 或更新版本；建议更新到当前官方版本，本次使用 2.1.289 完成真实调用验证。环境变量仅在当前终端会话中生效；在项目目录执行下面的配置。
export ANTHROPIC_BASE_URL="https://sotaai.org"
export ANTHROPIC_AUTH_TOKEN="YOUR_SOTA_API_KEY"
export ANTHROPIC_MODEL="claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
claude -p "Reply exactly SOTA_CLAUDE_OK."$env:ANTHROPIC_BASE_URL="https://sotaai.org"
$env:ANTHROPIC_AUTH_TOKEN="YOUR_SOTA_API_KEY"
$env:ANTHROPIC_MODEL="claude-sonnet-5-5"
$env:ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-5-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-5-5"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5-20251001"
claude -p "Reply exactly SOTA_CLAUDE_OK."如果终端已经设置 ANTHROPIC_API_KEY 或其他服务商变量，先检查冲突，确保这次会话使用 SOTA 地址和所选密钥。不要把密钥提交到项目仓库。
Anthropic SDK
安装官方 Python SDK：pip install anthropic。SDK 的 base_url 使用站点根地址，SDK 会追加 /v1/messages。
import os
from anthropic import Anthropic
client = Anthropic(base_url="https://sotaai.org", api_key=os.environ["ANTHROPIC_AUTH_TOKEN"])
with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=256,
messages=[{"role": "user", "content": "Reply exactly SOTA_CLAUDE_OK."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)其他客户端与协议
| 客户端 / 接口 | 填写方式 |
|---|---|
| Claude Code / Anthropic SDK | 提供商 Anthropic，根地址 https://sotaai.org |
| OpenCode | 提供商 Anthropic，API 地址 https://sotaai.org/v1；也可使用控制台密钥页面的配置模板 |
| OpenAI Chat Completions 客户端 | 地址 https://sotaai.org/v1，端点 /chat/completions，模型填 Claude 模型 ID |
| 原生 HTTP | POST /v1/messages；x-api-key 为本站密钥，anthropic-version 为 2023-06-01 |
| Token 预估 | POST /v1/messages/count_tokens |
仅支持 OpenAI Responses 的客户端不要套用 Claude Messages 配置。图片理解通过 Messages 的 image 输入块调用；图片生成仍使用 OpenAI 图片渠道。
工具、思考、缓存与结构化输出
- 工具调用使用 tools 声明工具，由客户端执行模型返回的 tool_use，再通过 tool_result 交回结果。Sonnet 5.5 使用 tool_choice: {"type":"auto"}；上游不接受强制 tool 或 any。
- 支持的模型可使用 thinking: {"type":"adaptive"} 和 output_config.effort。模型可能直接回答简单问题；未返回思考文本不表示请求失败。
- 结构化输出使用 output_config.format，类型为 json_schema。
- 缓存使用 cache_control: {"type":"ephemeral","ttl":"5m"}；也可按模型权限使用 1h。内容未达到模型最低长度或前缀改变时可能不命中。
- Fable 模型是否开放取决于账号套餐与管理员配置；在 Pro 上可能使用额外付费额度，不应仅凭模型名字推定已包含。
错误排查与验收
| 现象 | 检查项 |
|---|---|
| 401 | 本站密钥是否有效、是否过期；管理员检查 OAuth 授权状态 |
| 403 / model not allowed | 密钥是否绑定 Claude 分组，模型是否在白名单内 |
| 429 | 账号并发、5 小时与周额度；按 Retry-After 等待，避免反复重试 |
| claude_code_version_too_old | 升级 Claude Code；由管理员核对网关协议版本 |
| 工具参数 400 | 核对该模型支持的 tool_choice 和思考参数 |
验收包括模型列表、普通与流式响应、工具调用及结果回传、图片理解、结构化输出、缓存命中和使用记录。上游产品限制不会因为换成中转地址而自动消失。
发现内容有误，或有未解答的问题？反馈文档问题 ↗