CloudRouter 文档

English

简体中文

English

简体中文

Appearance

Quickstart: Your First Call in 5 Minutes ​

Applies to: Developers Updated: 2026-07-02

This guide takes you from scratch to your first API call in 5 minutes, seeing the model return a reply.

The API address is https://api.cloudrouter.online, with route prefix /v1, and authentication via Authorization: Bearer sk-xxx. You can also view the currently available Base URL on the console's "API Keys" page.

Prerequisites ​

Before you start, make sure you have:

  • ✅ A CloudRouter account (Organizations register themselves; Subusers register with an activation code)
  • ✅ Available balance / quota on the account (real charges always deduct from the owning Organization's balance; if your quota is 0, contact your owning Organization)

Step 1: Get an API Key ​

In v2, API Keys are created by the Organization in the console:

  • If you are an Organization (top-level user):

    1. Log in to console.cloudrouter.online
    2. Go to the "API Keys" page
    3. Click "Create API Key", give it a name (e.g. my-first-key), and bind it to a routing group
    4. After creation, immediately copy and save the Key (in the form sk-xxxxxxxx); it is shown in full only once

  • If you are a Subuser: you can self-serve create a Key on the "API Keys" page (the routing group is limited to what the Organization has authorized); or the Organization can create and distribute one for you.

    Subusers can self-serve create Keys on the "API Keys" page (each Key binds to one routing group, selectable only within the Organization's authorized scope); the Organization can also create and distribute them.

⚠️ An API Key is equivalent to a password. Do not commit it to a code repository or share it publicly.

Once you have the Key, you still need to decide what to put in the model field — see the next step.

Step 2: Get the call name from the "Call Guide" ​

Log in to the console, go to the "Call Guide" page, and copy the call name of the model you want to use:

  • Bare model name (e.g. gpt-4o): routes to the routing group bound to this Key.
  • With fingerprint (e.g. 5MHXZWKA/gpt-4o): calls out a specific group.

When you're unsure which to use, just copy directly from the Call Guide page — that's the safest. For the difference between the two forms and how to choose, see Call Guide & Dual Routing. This guide uses the bare model name in its examples.

Step 3: Send your first request (curl) ​

Replace YOUR_API_KEY in the command below with your Key, replace model with the call name you copied from the Call Guide, and run it in a terminal:

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": "Introduce yourself in one sentence"}
    ]
  }'

If all goes well, you'll receive a response like this:

json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "claude-sonnet-4-6",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "I'm an AI assistant that can help you answer questions, write code, and process text."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 20,
    "total_tokens": 32
  }
}

Congratulations — you've completed your first call!

Step 4: Call from Python ​

Closer to real development, using the official OpenAI SDK (you only change base_url and 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": "Introduce yourself in one sentence"}
    ]
)

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

Install the dependency: pip install openai

Quick troubleshooting ​

SymptomPossible causeFix
401 UnauthorizedWrong Key, or Bearer not includedCheck the Authorization header format
403 / insufficient balance or quotaOwning Organization's balance is 0, or Subuser quota is cappedContact the owning Organization to top up / raise the quota
Model unavailable / not foundWrong call name, or not within your account's available rangeCopy the call name from the Call Guide, confirm your available range
Fingerprint call reports "group unreachable"The group is out of your available range or its channel is unavailableSee Call Guide & Dual Routing
429Quota / rate limit exhaustedReduce request frequency, see Errors & Troubleshooting

For the full list of error codes, see Errors & Troubleshooting.

Next steps ​

Contact us ​