API 调用基础
适用角色：开发者 更新日期：2026-08-06
本页说明 API 地址、认证、对话请求、流式输出、模型切换和两种兼容协议的差异。
本平台 API 地址请在控制台查看，OpenAI Compatible 路由前缀为
/v1。
一、Base URL 与认证
端点一览
| 端点 | 协议 / 用途 |
|---|---|
POST /v1/chat/completions |
OpenAI 格式对话 |
POST /v1/messages |
Messages 兼容格式对话 |
GET /v1/models |
获取可用模型列表 |
Base URL 请在控制台查看。SDK 或客户端会按所选协议拼接请求路径；需要填写完整请求地址时，再使用上表中的对应端点。以控制台「API Key -- 使用密钥」给出的配置为准。
认证
所有请求通过 HTTP Header 携带 API Key（sk- 开头）：
Authorization: Bearer YOUR_API_KEY认证方式以控制台「使用密钥」给出的配置为准。
二、发起对话请求（OpenAI 格式）
最小请求
curl https://<接口地址>/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [
{"role": "system", "content": "你是一个专业的中文助手。"},
{"role": "user", "content": "什么是大语言模型？"}
]
}'常用参数
| 参数 | 必填 | 说明 |
|---|---|---|
model |
是 | 模型调用名，填模型名称（如 deepseek-v4-flash、kimi-k3），系统按默认路由解析分组。分组标识路由开启后也可填带分组标识的调用名（如 5MHXZWKA/deepseek-v4-flash），详见 调用指南与路由说明 |
messages |
是 | 对话历史数组，每条含 role 和 content |
stream |
否 | 是否流式输出，默认 false |
temperature |
否 | 采样温度，0 |
max_tokens |
否 | 限制生成的最大 Token 数 |
role取值：system（系统指令）、user（用户输入）、assistant（模型回复）。
三、流式输出（Stream）
设置 stream: true，响应会以 SSE（Server-Sent Events）逐块返回，适合打字机效果的实时渲染。
from openai import OpenAI
client = OpenAI(
api_key="YOUR_API_KEY",
base_url="https://<接口地址>"
)
stream = client.chat.completions.create(
model="deepseek-v4-flash",
messages=[{"role": "user", "content": "写一首关于春天的短诗"}],
stream=True
)
for chunk in stream:
delta = chunk.choices[0].delta.content
if delta:
print(delta, end="", flush=True)原始 SSE 数据形如：
data: {"choices":[{"delta":{"content":"春"}}]}
data: {"choices":[{"delta":{"content":"风"}}]}
data: [DONE]注意：流式错误处理：如果模型在流传输中途出错，你会收到一个 error 事件后连接断开（此时前面的内容已部分送达）。务必在 SSE 解析逻辑中处理 error 事件，详见 错误码与排障。
四、切换模型
切换模型只需改 model 字段的值。可用的调用名取决于你账户的可用模型范围，可在控制台「调用指南」或模型广场查看。
# 复杂任务用 高性能模型 档
resp = client.chat.completions.create(model="kimi-k3", messages=[...])
# 日常任务用 通用模型 档
resp = client.chat.completions.create(model="deepseek-v4-flash", messages=[...])如果需要精确指定分组，开启分组标识路由后可使用带分组标识的调用名（如
5MHXZWKA/deepseek-v4-flash）。详见 调用指南与路由说明。 在 Claude Code 工具中通过/model选择模型时，平台会按映射关系路由到对应模型，具体可用模型以控制台「调用指南」为准。
五、Messages 兼容格式调用
如果你使用 Messages 兼容协议，可用 /v1/messages 端点：
curl https://<接口地址>/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": "你好"}
]
}'两套格式怎么选
| 维度 | OpenAI Compatible (/v1/chat/completions) |
Messages Compatible (/v1/messages) |
|---|---|---|
max_tokens |
可选 | 必填 |
system 指令 |
放进 messages 数组 |
独立的 system 顶层字段 |
| 生态兼容 | 大多数 SDK 和框架 | 使用 Messages 格式的 SDK、Claude Code 工具 |
| 推荐场景 | 通用、迁移已有 OpenAI 代码 | 使用 Messages 兼容格式 |
按客户端和目标模型实际支持的协议选择；可用协议以控制台「调用指南」为准。
六、完整示例：多轮对话
from openai import OpenAI
client = OpenAI(api_key="YOUR_API_KEY", base_url="https://<接口地址>")
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="deepseek-v4-flash", messages=messages)
reply = resp.choices[0].message.content
print("助手：", reply)
messages.append({"role": "assistant", "content": reply}) # 保留上下文