使用 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 執行相同的查詢。請將 API 金鑰頁面核發的金鑰填入 sk-... 的位置。

使用 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 一併告知我們。若是您直接指定的值，便可立即與用戶端記錄進行比對。