API Call Basics

Applies to: Developers Last updated: 2026-07-14

This article covers the core of API calls: 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 YOUR_API_BASE_URL, with the route prefix /v1. You can also view the currently available Base URL on the "API Keys" page in the console.

1. Base URL and Authentication

Endpoint Overview

In SDKs, you usually only need to configure the base address YOUR_API_BASE_URL, and the SDK will automatically append paths such as /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. Making a Chat Request (OpenAI Format)

Minimal Request

curl YOUR_API_BASE_URL/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": "什么是大语言模型？"}
    ]
  }'

Common Parameters

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

3. Streaming Output (Stream)

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

from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="YOUR_API_BASE_URL"
)
 
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)

Raw SSE data looks like:

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

⚠️ Streaming error handling: If the model errors midway through the stream, you will receive an error event and then the connection is dropped (at which point the preceding content has already been partially delivered). Be sure to handle the error event in your SSE parsing logic; see Error Codes and Troubleshooting for details.

4. Switching Models

To switch models, simply change the value of the model field. The available call names depend on the range of models available to your account, which you can view in the console under "Call Guide" or the Model Marketplace.

# 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 need to specify a group precisely, after enabling group-identifier routing you can use a call name with a group identifier (e.g., 5MHXZWKA/gpt-4o). See Call Guide and Routing for details. When selecting a tier via /model in Claude Code, the platform routes to the corresponding model based on the mapping; the specific available models are subject to the console's "Call Guide".

5. Anthropic-Format Calls

If you are accustomed to Claude's native protocol, you can use the /v1/messages endpoint:

curl YOUR_API_BASE_URL/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": "你好"}
    ]
  }'

How to Choose Between the Two Formats

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

6. Complete Example: Multi-Turn Conversation

from openai import OpenAI
 
client = OpenAI(api_key="YOUR_API_KEY", base_url="YOUR_API_BASE_URL")
 
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})  # 保留上下文

Next Steps

• Understand how to write the model field → Call Guide and Routing
• Integrate with an SDK / framework → SDK Integration
• Connect Claude Code / Cursor → Third-Party Tool Integration
• Handle errors → Error Codes and Troubleshooting