回傳 401／403 的 OpenAI 相容 API——base_url 與標頭陷阱

OpenAI 相容 API 的核心理念是 SDK 應該直接運作——因此當它回傳 401 時，錯誤幾乎總是在你變更的兩行：base_url 與 api_key。以下依照實際發生的順序列出失敗模式。

錯誤

response (HTTP 401)

{
  "error": {
    "type": "invalid_api_key",
    "message": "Invalid or missing API key.",
    "code": "invalid_api_key"
  }
}

原因與解決方法一覽

原因	解決方法
base_url 缺少 /v1 後綴（或重複加入）	大多數閘道要求精確使用 https://host/v1——SDK 會自行附加 /chat/completions。
來自其他主機的金鑰	sk-… 金鑰只能向簽發它的服務進行驗證；請檢查前綴 ↔ 主機是否相符。
企業代理伺服器／WAF 剝除 Authorization 標頭	從乾淨的網路進行測試；設定代理伺服器以轉送 Authorization。
OPENAI_API_KEY 環境變數覆寫你明確指定的金鑰	SDK 預設會讀取環境變數——在某些設定中，過時的環境變數會靜默地勝出；請明確傳入 api_key。

確認 SDK 實際呼叫的精確 URL

列印 client.base_url 並呼叫 GET /v1/models——這是成本最低的已驗證端點。如果 /models 可運作，驗證就沒有問題，錯誤出在其他地方：

check.py

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",   # exactly one /v1
    api_key="sk-kn-...",                 # explicit beats env vars
)
print(client.base_url)
print([m.id for m in client.models.list().data][:5])

用 Curl 呼叫相同主機以排除 SDK 問題

如果帶有 Authorization: Bearer 的 curl 可運作而 SDK 不行，請比較 SDK 的實際請求（設定 OPENAI_LOG=debug）——十次有九次是代理伺服器或環境變數改寫了某些內容。

如果你透過 Kunavo 呼叫

Kunavo 的端點在 https://api.kunavo.com/v1 上嚴格遵循 OpenAI 形狀，並使用 Bearer 驗證；GET /v1/models 可作為驗證冒煙測試。如果你的程式原本對 api.openai.com 執行，將 base_url 指向 Kunavo 是唯一需要的變更——相同的 SDK、相同的線路格式，一把金鑰即可呼叫 Claude、GPT 與媒體模型。

常見問題

閘道上的 401 與 403 有什麼不同？

401＝憑證本身未被接受（缺少／無效的金鑰）。403＝金鑰有效，但不允許執行該操作（停用的金鑰、遭停權的帳戶、未獲允許的模型）。請閱讀錯誤內容——相容 API 會將原因放在 error.message 中。

為什麼我的程式在本機可運作，在 CI 中卻回傳 401？

CI 是不同的環境：秘密未設定、設定給了不同的服務，或代理伺服器剝除了標頭。請在 CI 內記錄 repr(key[:12]) 與 base_url，以查看實際傳送的內容。