CloudRouter 文档

简体中文

English

简体中文

English

Appearance

API 调用基础 ​

适用角色：开发者 更新日期：2026-07-02

本文讲清楚 API 调用的核心：地址、认证、对话请求、流式输出、切换模型，以及两套协议格式的差异。覆盖日常 90% 的调用场景。

API 地址为 https://api.cloudrouter.online，路由前缀 /v1。你也可以在控制台「API 密钥」页查看当前可用的 Base URL。

一、Base URL 与认证 ​

端点一览 ​

端点协议 / 用途
POST /v1/chat/completionsOpenAI 格式对话
POST /v1/messagesAnthropic 格式对话
GET /v1/models获取可用模型列表
POST /v1/messages/count_tokensToken 计数（预估用量）；仅 Anthropic 系分组支持，OpenAI 分组调用返回 404
GET /v1/usage查询当前 Key 维度的用量与额度剩余（非组织账户余额，组织余额请在控制台查看），示例：curl https://api.cloudrouter.online/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
GET /v1beta/models · POST /v1beta/models/*Gemini 原生格式

在 SDK 中通常只需配置基础地址 https://api.cloudrouter.online/v1，SDK 会自动拼接 /chat/completions 等路径。

认证 ​

所有请求通过 HTTP Header 携带 API Key（sk- 开头）：

Authorization: Bearer YOUR_API_KEY

也兼容 x-api-key（Anthropic 风格）和 x-goog-api-key（Gemini 风格）头。

二、发起对话请求（OpenAI 格式） ​

最小请求 ​

bash
curl https://api.cloudrouter.online/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [
      {"role": "system", "content": "你是一个专业的中文助手。"},
      {"role": "user", "content": "什么是大语言模型？"}
    ]
  }'

常用参数 ​

参数必填说明
model✅模型调用名，可填裸模型名（如 claude-sonnet-4-6、gpt-4o）或带指纹（如 5MHXZWKA/gpt-4o），写法见 调用指南与双路由
messages✅对话历史数组，每条含 role 和 content
stream❌是否流式输出，默认 false
temperature❌采样温度，0~2，越低越稳定（中文场景建议 0.2~0.7）
max_tokens❌限制生成的最大 Token 数

role 取值：system（系统指令）、user（用户输入）、assistant（模型回复）。

三、流式输出（Stream） ​

设置 stream: true，响应会以 SSE（Server-Sent Events）逐块返回，适合打字机效果的实时渲染。

python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.cloudrouter.online/v1"
)

stream = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "写一首关于春天的短诗"}],
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

原始 SSE 数据形如：

text
data: {"choices":[{"delta":{"content":"春"}}]}
data: {"choices":[{"delta":{"content":"风"}}]}
data: [DONE]

⚠️ 流式错误处理：如果模型在流传输中途出错，你会收到一个 error 事件后连接断开（此时前面的内容已部分送达）。务必在 SSE 解析逻辑中处理 error 事件，详见 错误码与排障。

四、切换模型 ​

切换模型只需改 model 字段的值。可用的调用名取决于你账户的可用模型范围与这把 Key 绑定的路由分组，可在控制台「调用指南」页查看并复制。

python
# 复杂任务用 Opus 档
resp = client.chat.completions.create(model="claude-opus-4-7", messages=[...])

# 日常任务用 Sonnet 档
resp = client.chat.completions.create(model="claude-sonnet-4-6", messages=[...])

如果想用同一把 Key 灵活点名不同分组，把 model 改成带指纹的调用名即可，例如 5MHXZWKA/gpt-4o。机制见 调用指南与双路由。 Claude Code 中通过 /model 选择档位时，CloudRouter 会按映射关系路由到对应模型，具体可用模型以控制台「调用指南」为准。

五、Anthropic 格式调用 ​

如果你习惯 Claude 原生协议，可用 /v1/messages 端点：

bash
curl https://api.cloudrouter.online/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  }'

两套格式怎么选 ​

维度OpenAI 格式 (/v1/chat/completions)Anthropic 格式 (/v1/messages)
max_tokens可选必填
system 指令放进 messages 数组独立的 system 顶层字段
生态兼容OpenAI SDK、大多数框架Anthropic SDK、Claude Code
推荐场景通用、迁移已有 OpenAI 代码重度使用 Claude 特性

同一个模型两套格式都能调，按你的现有代码生态选即可。

六、完整示例：多轮对话 ​

python
from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.cloudrouter.online/v1")

messages = [{"role": "system", "content": "你是一个简洁的助手。"}]

while True:
    user_input = input("你：")
    if user_input == "exit":
        break
    messages.append({"role": "user", "content": user_input})

    resp = client.chat.completions.create(model="claude-sonnet-4-6", messages=messages)
    reply = resp.choices[0].message.content
    print("助手：", reply)

    messages.append({"role": "assistant", "content": reply})  # 保留上下文

下一步 ​

联系我们 ​

  • 电子邮箱：support_cloudrouter@clouditera.com
  • QQ 社群：712273971
  • 平台网址：cloudrouter.online