API 接入教程

白雲 API 教程：Chat 文本介面

白雲SI編輯組2026-10-09約 7 分鐘閱讀

Chat Completions 同步與 SSE 流式純文字請求範例。附完整檢查步驟、實操驗證和錯誤處理。

Chat Completions 文本介面

介面地址：POST https://api.baiyun.si/v1/chat/completions。

當前提供 Chat 形式的純文字對話，可用於明確支援 OpenAI 相容 Chat 協議的客戶端。請求要使用本站金鑰，並提交本次對話需要的完整文本上下文。

請求結構

{
  "model": "gpt-6-luna",
  "messages": [
    {"role": "system", "content": "用简洁的中文回答。"},
    {"role": "user", "content": "请解释什么是 Token。"}
  ],
  "stream": false
}

model 是本站實際開放的模型名稱;messages 是按順序提交的文本消息;stream 決定同步返回或流式返回。本文只展示已開放的基礎文本結構，複雜 SDK 參數及擴展功能不應預設可用。

同步呼叫

curl --fail-with-body https://api.baiyun.si/v1/chat/completions \
  -H "Authorization: Bearer $BAIYUN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"gpt-6-luna","messages":[{"role":"user","content":"用一句话解释 Token。"}],"stream":false}'

生成文本位於 choices[].message.content；用量資訊位於 usage。具體內容、Token 數和費用以本次實際響應及消費記錄為準。

流式呼叫

curl --no-buffer --fail-with-body https://api.baiyun.si/v1/chat/completions \
  -H "Authorization: Bearer $BAIYUN_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"gpt-6-luna",
    "messages":[{"role":"user","content":"用三句话介绍 Token。"}],
    "stream":true,
    "stream_options":{"include_usage":true}
  }'

流式返回採用 SSE：讀取 data: 中的 JSON，按順序拼接 choices[].delta.content。data: [DONE] 表示該流結束; 啟用 include_usage 後需保留末尾用量消息。不要將 SSE 的每一個分片視為獨立 HTTP 回應。

對話上下文與參數邊界

目前通道使用模型預設取樣。temperature、top_p、frequency_penalty 和 presence_penalty 暫不提供可調控制; 客戶端常見的預設值會由相容處理移除，不會改變模型的採樣設定。

多輪對話應在 messages 中提交必要的完整文本歷史。當前暫停外部工具、聯網、圖片及文件等功能，也不提供通過不可檢查的外部歷史繞過文本提交的方式。

某些模型或客戶端對輸出參數的支持不同。即使請求填寫 max_tokens、max_completion_tokens 或 8192 等數值，也不能把它當作本站已經保證的輸出長度或費用硬上限。請從簡短請求開始，核對消費記錄，並為密鑰設置適合自己的餘額限制。

同一憑據最多同時進行 2 個請求；模型調用還受頻率限制。遇到 429 先等待，按錯誤說明判斷原因，避免高頻循環重試。

實操前的檢查清單

準備自己的帳戶與呼叫金鑰，不使用他人的共享憑據。
記錄客戶端版本、系統和準備使用的模型，便於排查時復現。
儲存原配置或截圖，隱藏金鑰、驗證碼與私人內容。
確認測試可能消費少量 DK，先用一句話、一次請求開始。
查閱當前模型廣場與狀態頁，再決定是否啟用更多功能。

詳細排查：按順序縮小問題範圍

先確認帳戶已完善、密鑰有效、DK 餘額足夠，再核對協議、地址與模型。用同一密鑰做一次最小文本請求; 它成功以後，才逐項恢復附件、工具或自動重試。客戶端配置儲存後重新打開會話，避免舊會話仍使用先前供應商。

怎樣確認本節已經學會

不要只檢查「配置保存成功」提示。你應能說清當前 Base URL、密鑰用途、選用模型和請求協議，能在相應控制台核對自己的操作結果。客戶端教程以一次實際純文本響應和對應日誌為初步完成標準; 賬戶教程以安全信息完善為標準; 計費教程以本金、通道費與 DK 的對應關係核對為標準。

如果出現錯誤，記錄發生時間、HTTP 狀態、脫敏錯誤內容以及實際期待的結果。不要截圖整頁密鑰，也不要把密碼和驗證碼交給其他人。對 401 應先解決認證，對 400 應先解決參數，對 429 應停止密集重試，對 404 應核對請求路徑與上游是否實現，不能用重新充值解決所有報錯。

一個適合練習的小任務

在自己的測試環境完成本節的最小步驟，用文字記錄「原來怎麼設置、改了哪一項、看到了什麼結果」。不把生產資料、真實付款或不可恢復的命令當練習。遇到超出本節的功能，先查看對應協議教程，再考慮添加功能; 一次只變更一個配置，容易判斷哪一步導致錯誤。

下一步與版本邊界

返回完整學習地圖 · API 站精簡配置 · 本站即時狀態。

教程於2026年10月9日整理。具體介面與能力可能隨客戶端和上游版本變化; 配置指引不等於所有客戶端版本已經實測通過。本站餘額消費、QQ / 支付寶登錄及已開放通路以實際頁面為準; 壓縮介面此前的上游 404、生圖尚無可用渠道等限制不要理解為配置文件能自動消除。

返回社區，繼續閱讀分享我的經驗