首次请求
在 完成认证配置 之后，你就可以发起第一次 API 请求了。本指南将带你逐步了解请求的各个部分，并解释响应内容。
基础请求
最常用的端点是 Chat Completions（对话补全），它会根据一组消息生成响应：
curl https://openapi.linkwo.ai/v1/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek/deepseek-v4-pro",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the capital of France?"}
],
"temperature": 0.7
}'理解响应
成功请求后会返回如下 JSON：
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1719000000,
"model": "deepseek/deepseek-v4-pro",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "The capital of France is Paris."
},
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 24,
"completion_tokens": 8,
"total_tokens": 32
}
}关键字段
| 字段 | 说明 |
|---|---|
id | 本次补全的唯一标识 |
choices | 补全候选数组（通常为一个） |
choices[].message | 助手的回复 |
choices[].finish_reason | 模型停止生成的原因（stop、length、content_filter） |
usage | 用于计费和监控的 token 计数 |
消息角色
每条消息都有一个 role，用于告诉模型如何理解该消息：
| 角色 | 说明 |
|---|---|
system | 设定助手的行为和性格 |
user | 终端用户的输入或指令 |
assistant | 模型此前的回复（用于多轮对话） |
多轮对话
加入历史消息即可保持上下文：
from openai import OpenAI
client = OpenAI(
base_url="https://openapi.linkwo.ai/v1",
api_key="YOUR_API_KEY"
)
response = client.chat.completions.create(
model="deepseek/deepseek-v4-pro",
messages=[
{"role": "system", "content": "You are a travel guide."},
{"role": "user", "content": "What's the best time to visit Japan?"},
{"role": "assistant", "content": "The best time to visit Japan is during spring (March-May) for cherry blossoms or autumn (October-November) for fall foliage."},
{"role": "user", "content": "What about budget-friendly options?"}
]
)
print(response.choices[0].message.content)常用参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
temperature | float | 1.0 | 控制随机性（0 = 确定，2 = 非常随机） |
max_tokens | int | 模型上限 | 响应中生成的最大 token 数 |
top_p | float | 1.0 | 核采样阈值 |
stream | bool | false | 生成过程中流式返回部分结果 |
错误处理
如果出现问题，API 会返回一个错误对象：
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_request_error",
"code": "invalid_api_key"
}
}常见 HTTP 状态码：
| 状态码 | 含义 |
|---|---|
| 400 | 请求错误 —— 请检查参数 |
| 401 | 未授权 —— API 密钥无效或缺失 |
| 429 | 超出速率限制 —— 请降低频率或升级套餐 |
| 500 | 服务器错误 —— 稍等片刻后重试 |
完整列表请见 错误码。