API Call Basics

Applicable role: Developer Last updated: 2026-08-06

This page explains the API endpoint, authentication, chat requests, streaming output, model switching, and differences between the two compatible protocols.

You can find the platform API endpoint in the console. The OpenAI Compatible route prefix is /v1.

1. Base URL and Authentication

Endpoint Overview

You can find the Base URL in the console. SDKs or clients will append the request path based on the selected protocol; use the corresponding endpoint from the table above only when you need to specify the full request URL. Refer to the configuration provided under "API Key -- Use Key" in the console.

Authentication

All requests carry an API Key (sk- prefixed) via the HTTP Header:

Authorization: Bearer YOUR_API_KEY

Refer to the configuration provided under "Use Key" in the console for authentication details.

2. Making a Chat Request (OpenAI Format)

Minimal Request

curl https://<your-api-endpoint>/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "You are a professional assistant."},
      {"role": "user", "content": "What is a large language model?"}
    ]
  }'

Common Parameters

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

3. Streaming Output (Stream)

Set stream: true to receive the response incrementally via SSE (Server-Sent Events), suitable for real-time typewriter-style rendering.

from openai import OpenAI
 
client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://<your-api-endpoint>"
)
 
stream = client.chat.completions.create(
    model="deepseek-v4-flash",
    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:

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

Note on streaming error handling: If the model encounters an error mid-stream, you will receive an error event and the connection will close (partial content may have already been delivered). Make sure your SSE parsing logic handles error events. 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 models accessible to your account, which you can view in the console under "Call Guide" or in the model plaza.

# Use a high-performance model for complex tasks
resp = client.chat.completions.create(model="kimi-k3", messages=[...])
 
# Use a general-purpose model for everyday tasks
resp = client.chat.completions.create(model="deepseek-v4-flash", messages=[...])

If you need to specify a group precisely, enable group identifier routing and use a call name with the group identifier (e.g., 5MHXZWKA/deepseek-v4-flash). See Call Guide and Routing for details. When selecting a model via /model in the Claude Code tool, the platform routes to the corresponding model based on the mapping. Refer to "Call Guide" in the console for the available models.

5. Messages-Compatible Format

If you use the Messages-compatible protocol, use the /v1/messages endpoint:

curl https://<your-api-endpoint>/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

Choosing Between the Two Formats

Choose based on the protocol your client and target model actually support. Refer to "Call Guide" in the console for available protocols.

6. Full Example: Multi-Turn Conversation

from openai import OpenAI
 
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://<your-api-endpoint>")
 
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="deepseek-v4-flash", messages=messages)
    reply = resp.choices[0].message.content
    print("Assistant:", reply)
 
    messages.append({"role": "assistant", "content": reply})  # Retain context

Next Steps

• Learn about the model field format --> 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