CloudRouter 文档

English

简体中文

English

简体中文

Appearance

API Basics ​

Applies to: Developers Updated: 2026-07-02

This guide covers the core of API calls: the address, authentication, chat requests, streaming output, switching models, and the differences between the two protocol formats. It covers 90% of everyday call scenarios.

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

1. Base URL and authentication ​

Endpoint overview ​

EndpointProtocol / purpose
POST /v1/chat/completionsOpenAI-format chat
POST /v1/messagesAnthropic-format chat
GET /v1/modelsGet the list of available models
POST /v1/messages/count_tokensToken counting (estimate usage); supported only by Anthropic-family groups, returns 404 for OpenAI groups
GET /v1/usageQuery usage and remaining quota at the current Key level (not the Organization account balance; view the Organization balance in the console), example: curl https://api.cloudrouter.online/v1/usage -H "Authorization: Bearer YOUR_API_KEY"
GET /v1beta/models · POST /v1beta/models/*Native Gemini format

In an SDK, you usually only need to set the base address https://api.cloudrouter.online/v1; the SDK automatically appends paths like /chat/completions.

Authentication ​

All requests carry the API Key (starting with sk-) via an HTTP header:

Authorization: Bearer YOUR_API_KEY

The x-api-key (Anthropic style) and x-goog-api-key (Gemini style) headers are also supported.

2. Sending a chat request (OpenAI format) ​

Minimal request ​

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": "You are a professional assistant."},
      {"role": "user", "content": "What is a large language model?"}
    ]
  }'

Common parameters ​

ParameterRequiredDescription
model✅The model call name; can be a bare model name (e.g. claude-sonnet-4-6, gpt-4o) or with a fingerprint (e.g. 5MHXZWKA/gpt-4o). For the syntax see Call Guide & Dual Routing
messages✅Array of conversation history, each item containing role and content
stream❌Whether to stream output, defaults to false
temperature❌Sampling temperature, 0–2; lower is more stable (0.2–0.7 recommended)
max_tokens❌Limit the maximum number of tokens generated

role values: system (system instructions), user (user input), assistant (model reply).

3. Streaming output (Stream) ​

Set stream: true and the response is returned chunk by chunk as SSE (Server-Sent Events), suitable for typewriter-effect real-time rendering.

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": "Write a short poem about spring"}],
    stream=True
)

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

Raw SSE data looks like:

text
data: {"choices":[{"delta":{"content":"Spring"}}]}
data: {"choices":[{"delta":{"content":" breeze"}}]}
data: [DONE]

⚠️ Streaming error handling: if the model errors midway through the stream, you'll receive an error event and then the connection drops (at which point the preceding content has already partially arrived). Be sure to handle the error event in your SSE parsing logic — see Errors & Troubleshooting.

4. Switching models ​

Switching models only requires changing the value of the model field. The available call names depend on your account's available model range and the routing group bound to this Key; you can view and copy them on the console's "Call Guide" page.

python
# Use the Opus tier for complex tasks
resp = client.chat.completions.create(model="claude-opus-4-7", messages=[...])

# Use the Sonnet tier for everyday tasks
resp = client.chat.completions.create(model="claude-sonnet-4-6", messages=[...])

If you want to flexibly call out different groups with the same Key, just change model to a call name with a fingerprint, e.g. 5MHXZWKA/gpt-4o. For the mechanics, see Call Guide & Dual Routing. When you select a tier via /model in Claude Code, CloudRouter routes to the corresponding model per the mapping; the specific available models are as shown on the console's "Call Guide".

5. Calling with the Anthropic format ​

If you're used to Claude's native protocol, use the /v1/messages endpoint:

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": "Hello"}
    ]
  }'

How to choose between the two formats ​

DimensionOpenAI format (/v1/chat/completions)Anthropic format (/v1/messages)
max_tokensOptionalRequired
system instructionsPlaced in the messages arraySeparate top-level system field
Ecosystem compatibilityOpenAI SDK, most frameworksAnthropic SDK, Claude Code
Recommended forGeneral use, migrating existing OpenAI codeHeavy use of Claude features

The same model can be called with either format; choose based on your existing code ecosystem.

6. Full example: multi-turn conversation ​

python
from openai import OpenAI

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

messages = [{"role": "system", "content": "You are a concise assistant."}]

while True:
    user_input = input("You: ")
    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("Assistant: ", reply)

    messages.append({"role": "assistant", "content": reply})  # keep the context

Next steps ​

Contact us ​