API 调用基础
适用角色：开发者 更新日期：2026-07-14
本文讲清楚 API 调用的核心：地址、认证、对话请求、流式输出、切换模型，以及两套协议格式的差异。覆盖日常 90% 的调用场景。
API 地址为
YOUR_API_BASE_URL，路由前缀/v1。你也可以在控制台「API 密钥」页查看当前可用的 Base URL。
一、Base URL 与认证
端点一览
| 端点 | 协议 / 用途 |
|---|---|
POST /v1/chat/completions |
OpenAI 格式对话 |
POST /v1/messages |
Anthropic 格式对话 |
GET /v1/models |
获取可用模型列表 |
POST /v1/messages/count_tokens |
Token 计数（预估用量）；仅 Anthropic 系分组支持，OpenAI 分组调用返回 404 |
GET /v1/usage |
查询当前 Key 维度的用量与额度剩余（非组织账户余额，组织余额请在控制台查看），示例：curl YOUR_API_BASE_URL/usage -H "Authorization: Bearer YOUR_API_KEY" |
GET /v1beta/models · POST /v1beta/models/* |
Gemini 原生格式 |
在 SDK 中通常只需配置基础地址
YOUR_API_BASE_URL，SDK 会自动拼接/chat/completions等路径。
认证
所有请求通过 HTTP Header 携带 API Key（sk- 开头）：
Authorization: Bearer YOUR_API_KEY也兼容
x-api-key（Anthropic 风格）和x-goog-api-key（Gemini 风格）头。
二、发起对话请求（OpenAI 格式）
最小请求
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": "什么是大语言模型？"}
]
}'常用参数
| 参数 | 必填 | 说明 |
|---|---|---|
model |
✅ | 模型调用名，填模型名称（如 claude-sonnet-4-6、gpt-4o），系统按默认路由解析分组。分组标识路由开启后也可填带分组标识的调用名（如 5MHXZWKA/gpt-4o），详见 调用指南与路由说明 |
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="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)原始 SSE 数据形如：
data: {"choices":[{"delta":{"content":"春"}}]}
data: {"choices":[{"delta":{"content":"风"}}]}
data: [DONE]⚠️ 流式错误处理：如果模型在流传输中途出错，你会收到一个 error 事件后连接断开（此时前面的内容已部分送达）。务必在 SSE 解析逻辑中处理 error 事件，详见 错误码与排障。
四、切换模型
切换模型只需改 model 字段的值。可用的调用名取决于你账户的可用模型范围，可在控制台「调用指南」或模型广场查看。
# 复杂任务用 Opus 档
resp = client.chat.completions.create(model="claude-opus-4-7", messages=[...])
# 日常任务用 Sonnet 档
resp = client.chat.completions.create(model="claude-sonnet-4-6", messages=[...])如果需要精确指定分组，开启分组标识路由后可使用带分组标识的调用名（如
5MHXZWKA/gpt-4o）。详见 调用指南与路由说明。 Claude Code 中通过/model选择档位时，平台会按映射关系路由到对应模型，具体可用模型以控制台「调用指南」为准。
五、Anthropic 格式调用
如果你习惯 Claude 原生协议，可用 /v1/messages 端点：
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": "你好"}
]
}'两套格式怎么选
| 维度 | OpenAI 格式 (/v1/chat/completions) |
Anthropic 格式 (/v1/messages) |
|---|---|---|
max_tokens |
可选 | 必填 |
system 指令 |
放进 messages 数组 |
独立的 system 顶层字段 |
| 生态兼容 | OpenAI SDK、大多数框架 | Anthropic SDK、Claude Code |
| 推荐场景 | 通用、迁移已有 OpenAI 代码 | 重度使用 Claude 特性 |
同一个模型两套格式都能调，按你的现有代码生态选即可。
六、完整示例：多轮对话
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}) # 保留上下文