使用 API 金鑰進行驗證

CLEVI 閘道會透過一個 API 金鑰，驗證 OpenAI 相容路徑及 Anthropic 相容路徑。
用戶端需要設定兩項值：放置金鑰的驗證標頭，以及 SDK 的 base URL；允許的標頭格式和 base URL 會因規格而異。
完成設定後，查詢模型清單即可立即確認是否通過驗證。
如果驗證失敗，會返回 401；驗證通過後如未符合權限或額度條件，則會返回 403。

請在主控台的 API 金鑰頁面發行 API 金鑰。您亦可在同一頁面管理金鑰的撤銷及使用範圍。

驗證標頭

兩種規格均會將 API 金鑰放入其中一個請求標頭。您可以使用 X-API-Key 標頭或 Authorization 標頭，而允許的格式會因規格而異。

在 OpenAI 相容路徑中使用 Authorization 標頭時，需要 Bearer 前綴。如果只傳送金鑰而不含前綴，閘道會拒絕請求。

標頭名稱不區分大小寫，因此 Anthropic SDK 傳送的 x-api-key 標頭亦可直接運作。如果同時指定兩個標頭，會優先採用 X-API-Key 的值。

base URL

現有使用中的 SDK 只需將 base URL 更改為以下地址即可繼續使用。兩個地址的差異在於是否包含 /v1，請按照規格直接指定相應地址。

確認驗證

設定金鑰和 base URL 後，查詢模型清單即可確認是否已通過驗證。以下範例分別使用 curl、OpenAI SDK 和 Anthropic SDK 執行相同的查詢。請將 sk-... 位置替換為在 API 金鑰頁面簽發的金鑰。

使用 curl 查詢時，兩種規格都要指定完整路徑至 /v1/models。第一個指令在 OpenAI 相容路徑使用 X-API-Key 標頭，第二個指令在 Anthropic 相容路徑使用 Authorization 標頭。

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

OpenAI SDK 的 base_url 請指定包含 /v1 的地址。

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

Anthropic SDK 的 base_url 請指定以 /v1 之前結尾的地址。
驗證時直接使用 SDK 傳送的 x-api-key 標頭。

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

無論哪個範例，只要回應為 200，即表示驗證成功；回應中的 data 會包含可使用此金鑰呼叫的模型清單。如果回應為 401，請按照下一節的順序確認原因。

驗證失敗

如果傳送不存在、已過期或已撤銷的金鑰，會返回 401。在 OpenAI 相容路徑中不帶金鑰呼叫時，會返回以下本文；在 Anthropic 相容路徑中，error.type 為 authentication_error。

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

收到 401 時，請按以下順序確認。

1. 在 API 金鑰頁面確認金鑰狀態。如果金鑰已過期或已撤銷，請重新簽發。
2. 確認標頭名稱是否為 X-API-Key 或 Authorization。
3. 如果在 OpenAI 相容路徑使用 Authorization 標頭，請確認是否包含 Bearer 前綴。

修改後，重新執行驗證一節中的模型清單查詢，確認是否返回 200。

一併使用的標頭

以下標頭全部為可選項目。為便於追蹤問題，建議指定 X-Request-Id。

如果 5xx 錯誤重複出現，請連同 X-Request-Id 一併透過說明文件及查詢告知我們。如果是直接指定的值，便可立即與用戶端記錄進行比對。