首次請求
在 完成认證配置 之後，你就可以發起第一次 API 請求了。本指南將带你逐步了解請求的各個部分，並解釋響應內容。
基礎請求
最常用的端點是 Chat Completions（對話補全），它會根據一组消息生成響應：
curl https://api.linkastra.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://api.linkastra.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 | 伺服器錯誤 —— 稍等片刻後重試 |
完整列表請见 錯誤碼。