CloudRouter 文档

简体中文

English

简体中文

English

Appearance

快速开始：5 分钟首次调用 ​

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

本文带你从零开始，在 5 分钟内完成第一次 API 调用，看到模型返回的回复。

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

前置条件 ​

开始之前，确认你已经：

  • ✅ 拥有一个 CloudRouter 账号（组织账号自行注册，或子用户用激活码完成注册）
  • ✅ 账号有可用余额 / 额度（真实扣费始终扣所属组织的余额；额度为 0 时请联系所属组织）

第一步：拿到 API Key ​

v2 下 API Key 由组织在控制台创建：

  • 如果你是组织（顶层用户）：

    1. 登录 console.cloudrouter.online
    2. 进入「API 密钥」页面
    3. 点击「创建 API Key」，给它起个名字（如 my-first-key），并为其绑定一个路由分组
    4. 创建后立即复制保存 Key（形如 sk-xxxxxxxx），它只完整显示一次

  • 如果你是子用户：你可在「API 密钥」页自助创建 Key（路由分组限组织授权范围）；也可由组织代建分发。

    子用户可在「API 密钥」页自助创建 Key（每 Key 绑定一个路由分组，只能在组织授权范围内选）；组织也可代建分发。

⚠️ API Key 等同密码，请勿提交到代码仓库或公开分享。

拿到 Key 后，你还需要确定 model 字段写什么——见下一步。

第二步：去「调用指南」拿调用名 ​

登录控制台，进入「调用指南」页，复制你要用的模型调用名：

  • 裸模型名（如 gpt-4o）：路由到这把 Key 绑定的路由分组。
  • 带指纹（如 5MHXZWKA/gpt-4o）：点名到指定分组。

不确定写哪种时，直接在调用指南页复制最稳妥。两种写法的区别与场景选择见 调用指南与双路由。本文示例以裸模型名为例。

第三步：发送第一个请求（curl） ​

把下面命令里的 YOUR_API_KEY 换成你的 Key，model 换成你从调用指南复制的调用名，在终端执行：

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": "user", "content": "用一句话介绍你自己"}
    ]
  }'

如果一切正常，你会收到类似这样的响应：

json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "我是一个 AI 助手，可以帮你解答问题、编写代码、处理文本。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 20,
    "total_tokens": 32
  }
}

恭喜，你已经完成第一次调用！

第四步：用 Python 调用 ​

更贴近真实开发，用官方 OpenAI SDK（只需改 base_url 和 api_key）：

python
from openai import OpenAI

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

resp = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[
        {"role": "user", "content": "用一句话介绍你自己"}
    ]
)

print(resp.choices[0].message.content)

安装依赖：pip install openai

常见快速排错 ​

现象可能原因解决
401 UnauthorizedKey 错误或没填 Bearer检查 Authorization 头格式
403 / 余额或额度不足所属组织余额为 0，或子用户额度封顶联系所属组织充值 / 上调额度
模型不可用 / 找不到调用名写错，或不在你账户的可用范围内去调用指南复制调用名，确认可用范围
带指纹报"分组不可达"该分组不在可用范围或渠道不可用见 调用指南与双路由
429限额/限流耗尽降低请求频率，见 错误码与排障

完整错误码见 错误码与排障。

下一步 ​

联系我们 ​

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