EN 简体 登入 開始使用
開發文件

整套 API，
一頁就寫得完。

一智連天下使用 OpenAI 的請求格式。如果你呼叫過 OpenAI 相容介面，下面的內容會非常眼熟——這正是我們想要的效果。

API 位址與驗證

金鑰以 Bearer Token 方式傳遞。不要放進 URL 查詢參數，也不要打包進前端程式碼。

auth
Base URL   https://api.1ai.cloud/v1
Header     Authorization: Bearer $ONEAI_API_KEY
Header     Content-Type: application/json

對話補全

幾乎所有場景都用這個介面。model 可填 模型目錄裡的任意 id。

POST /v1/chat/completions
curl https://api.1ai.cloud/v1/chat/completions \
  -H "Authorization: Bearer $ONEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k3",
    "messages": [
      {"role": "system", "content": "回答請簡短。"},
      {"role": "user",   "content": "用一句話打個招呼。"}
    ],
    "temperature": 0.7,
    "stream": false
  }'

串流回傳

設定 stream: true 即可接收 SSE 事件流。串流以 data: [DONE] 結束，與 OpenAI SDK 的預期完全一致。

stream.py
stream = client.chat.completions.create(
    model="glm-5.2",
    messages=[{"role": "user", "content": "從一數到五。"}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

查詢可用模型

回傳目前金鑰可以路由到的全部模型。可以直接當作 CI 裡的健康檢查。

GET /v1/models
curl https://api.1ai.cloud/v1/models \
  -H "Authorization: Bearer $ONEAI_API_KEY"

備援與故障切換

傳入一串有序的備援模型。當主模型回傳限速、逾時或 5xx 時， 請求會在同一次呼叫內自動切換到下一個。

fallbacks.json
{
  "model": "claude-sonnet-5",
  "fallbacks": ["gpt-5.4", "glm-5.2", "kimi-k3"],
  "messages": [{"role": "user", "content": "..."}]
}

錯誤碼

狀態碼如何處理
401金鑰缺失、格式錯誤或已撤銷。檢查 Authorization 標頭。
402餘額不足，請在控制台儲值。
404模型 id 不存在。呼叫 GET /v1/models 查看目前金鑰可用的模型。
429上游限速。請退避重試，或宣告備援列表讓呼叫自動改道。
5xx上游故障。可安全地退避重試；設定備援列表後平台會替你處理。

實務建議

  • 按環境分別簽發金鑰。撤銷一把外洩的測試金鑰，不應該影響到正式環境流量。
  • 讓系統提示詞與工具定義在多輪之間保持逐位元組一致——這是快取命中價能生效的前提。
  • 在用戶端明確設定逾時。多數 SDK 的預設逾時都比使用者願意等的時間長得多。
  • 如果可重現性比「自動用上最新版本」更重要，請鎖定具體模型 id，而不是使用別名。
需要這裡沒寫到的能力——批次任務、向量嵌入、專屬區域，或一次資料處理評估？ ， 我們會給具體答覆，而不是一份宣傳手冊。