Keural API

以 OpenAI Chat Completions 格式呼叫 Keural 中登錄的模型。

Base URL 的格式為 https://<各環境的公開 API 網域>/llm/v1。公開 API 網域依環境而異，請向管理員確認。

嵌入、圖像生成、語音與 Responses API 路徑均不支援，會回傳 404。

使用流程複製錨點連結

準備事項複製錨點連結

發行 API 金鑰複製錨點連結

1. 在帳號選單中開啟 設定 → API。在桌面應用程式與行動應用程式中，它位於 工具 區域。
2. 在 API keys 分頁中，選擇金鑰的歸屬（個人工作區或組織工作區）以及 Model ID。
3. 如有需要，設定 New key expiration (optional, Korea time)。留空則在撤銷前一直有效。
4. 按下 Issue key，再用 Copy key 複製金鑰並妥善保存。完整金鑰僅會在此時顯示一次。

• 金鑰與所選工作區及一個模型相連。用量歸屬於發行金鑰的人。
• 同一工作區、同一模型只能有一把金鑰。若需要新金鑰，請重新發行或撤銷現有金鑰。
• 若遺失金鑰，請重新發行。重新發行後，先前的金鑰會立即無法使用。
• 若沒有可發行的模型，請向管理員確認模型公開設定、方案與組織 API 權限。

組織成員的 API 權限複製錨點連結

僅適用於組織擁有者與管理員。要讓成員在組織工作區中取得金鑰，需由管理員先行允許。所有成員的預設皆為封鎖。

組織管理 → Organization API 由以下三個區域組成。若沒有此選單，表示 API 功能已關閉，或此帳號沒有組織管理權限。

成員離開或被移出組織時，該成員在組織中取得的金鑰會自動撤銷。

連接到用戶端複製錨點連結

請在相容 OpenAI API 的應用程式（聊天用戶端、IDE 擴充功能、自動化工具等）中，輸入以下三個值。

1. 在應用程式設定中新增 OpenAI 相容連線（Connection）。
2. 輸入 Base URL 與 API Key，然後儲存。
3. 從模型清單中選擇模型。清單中只會顯示與金鑰相連的一個模型。
4. 傳送簡短訊息，確認有收到回應。

請求格式如下。

第一個請求複製錨點連結

export KEURAL_API_KEY='your_issued_key'
export KEURAL_BASE_URL='https://<各環境的公開 API 網域>/llm/v1'
export MODEL_ID='發行畫面中的模型 ID'

curl "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"你好。\"}]}"

請求本文中的 model 必須與金鑰連接的模型 ID 相同。若前面帶有 provider/模型ID 這樣的路徑，會比較最後一個 / 之後的部分。不同時會回傳 403。回應中的 model 一律包含金鑰的模型 ID。

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["KEURAL_API_KEY"],
    base_url=os.environ["KEURAL_BASE_URL"],
)
res = client.chat.completions.create(
    model=os.environ["MODEL_ID"],
    messages=[{"role": "user", "content": "你好。"}],
)
print(res.choices[0].message.content)

支援的請求欄位複製錨點連結

頂層欄位僅接受以下 18 個。傳送其他欄位會回傳 400。值為 null 的選用欄位視為未傳送。

訊息複製錨點連結

• tool 訊息對前面 tool_calls 中的每個 id 只回覆一次。
• 圖像片段（image_url）只能放在支援圖像的模型之 user 訊息中。可使用 http 或 https 位址，或 PNG、JPEG、GIF、WebP 的 base64 data URI。detail 為 auto、low 或 high。

本文複製錨點連結

違反本文規則會回傳 400，且 param 為 body。

串流複製錨點連結

在請求中加入 "stream": true 後，會以 SSE 回應。各區塊以 data: ... 事件傳送，最後會傳送 data: [DONE]。若加入 "stream_options": {"include_usage": true}，則在 [DONE] 之前會額外傳送一個權杖用量區塊。

加入 include_usage 後，每個區塊都會包含 usage: null，最後一個用量區塊的 choices 為空陣列。非串流回應只有在輸入與輸出權杖都已確認時才會包含 usage。

回應的 id 格式為 chatcmpl-<x-request-id>。所有回應標頭都包含 x-request-id。

串流中發生錯誤時，會傳送含有錯誤 JSON 的 data: 事件，然後在沒有 [DONE] 的情況下結束連線。若單一區塊超過 1MiB，或回應超過 16MiB，則會以 503 結束。

curl -N "$KEURAL_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $KEURAL_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$MODEL_ID\",\"messages\":[{\"role\":\"user\",\"content\":\"你好。\"}],\"stream\":true,\"stream_options\":{\"include_usage\":true}}"

使用限制複製錨點連結

依使用者、組織與模型為單位，限制同時請求數、每分鐘請求數（RPM）與每分鐘權杖數（TPM）。實際數值依環境而異。

每分鐘權杖數會在接收請求時預先扣除。輸入以每 4 個英文字元計 1 個權杖，其他字元以每個字元計 1 個權杖，一張圖像計 2,000 個權杖。輸出依 max_tokens（最多 4,096）預先扣除，因此只設定所需的輸出上限，可以讓限額更有餘裕。

金鑰管理複製錨點連結

在 設定 → API → API keys 分頁中，可以確認已發行金鑰的狀態（有效、已過期、已撤銷），並進行重新發行或撤銷。

金鑰是以 krl_llm_ 開頭、共 51 個字元的字串。每個金鑰歸屬只能有一把金鑰，已存在時會重新發行。有效期限只能設定為今天之後的日期。

查看用量複製錨點連結

透過 API 傳送的請求與消耗的權杖，可在以下兩個位置確認。

查詢條件複製錨點連結

設定條件後按下 Search。若要反映最近的請求，請按下 Refresh。

畫面上顯示的值複製錨點連結

• Applied time range (KST)：實際查詢的時間範圍。開始與結束時間留空或超過 90 天時，會顯示伺服器調整後的時間範圍。
• Requests 與 Input tokens · Output tokens · Total tokens 的合計：只加總已確認的值。未確認的權杖以 Unconfirmed 顯示。
• 請求清單：每個請求顯示請求時間、Model ID、請求狀態，以及輸入、輸出、總權杖數。每頁顯示 20 筆，以 Previous 與 Next 翻頁。

按下列中的 Request details，即可顯示以下數值。

串流請求即使沒有 stream_options.include_usage，也會記錄用量。若請求中途中斷，可能會保留為 Partially confirmed 或 Unconfirmed。

錯誤格式複製錨點連結

錯誤以 OpenAI 相容格式回傳。

{
  "error": {
    "message": "供人閱讀的錯誤說明",
    "type": "authentication_error",
    "code": "invalid_api_key",
    "param": null
  }
}

type 由狀態碼決定，code 用於區分原因。

疑難排解複製錨點連結

問題仍未解決時，請附上以下資訊聯絡管理員。請勿傳送金鑰全文與提示詞內容。

• 發生時間
• 使用的模型 ID
• 用戶端應用程式的名稱與版本
• 回應標頭中的 x-request-id
• 畫面上顯示的錯誤訊息