身分驗證
每個 API 請求都使用工作區建立的 Bearer Token。
Vergora API 使用 API Key 驗證請求身分。所有請求都應從伺服器端傳送,並透過
Authorization請求標頭傳遞憑證。
請求標頭格式
Authorization: Bearer YOUR_VERGORA_API_KEYBearer 與 API Key 之間必須保留一個空格。不要把 API Key 放在 URL 查詢參數中。
建立 API Key
- 登入主控台並開啟 API Keys。
- 建立一個新的 API Key。
- 使用能夠識別應用程式和環境的名稱,例如
storefront-production。 - 根據應用程式需要設定預算、有效期限和模型存取範圍。
- 依頁面提示複製並妥善保存完整 API Key。
設定建議
| 設定 | 建議 |
|---|---|
| 名稱 | 包含應用程式和環境,避免使用無法識別的名稱 |
| 環境 | 為開發、測試和正式環境分別建立 Key |
| 預算 | 根據應用程式的預期用量設定,不要把 Key 預算理解為錢包儲值 |
| 有效期限 | 臨時測試使用較短期限,正式環境定期檢查 |
| 模型範圍 | 只開放應用程式實際需要的模型 |
| 來源限制 | 啟用後,只填寫應用程式實際使用的出口位址 |
在應用程式中使用
export VERGORA_API_KEY="YOUR_VERGORA_API_KEY"應用程式從伺服器端環境變數或金鑰管理工具讀取該值。不要把完整 Key 寫入原始碼、瀏覽器指令碼、公開儲存庫、日誌或截圖。
輪換與停止使用
- 建立替代 Key。
- 更新應用程式設定並傳送最小請求。
- 在 Requests 中確認新 Key 的請求成功。
- 停止使用舊 Key。
- 檢查是否還有應用程式繼續使用舊憑證。
如果完整 Key 遺失,請依主控台提供的流程建立替代憑證。懷疑憑證外洩時,應立即停止使用該憑證並檢查相關請求紀錄。
驗證失敗疑難排解
| 檢查項目 | 處理方式 |
|---|---|
| API Key 為空或不完整 | 重新讀取伺服器端環境變數 |
| 請求標頭格式錯誤 | 使用 Authorization: Bearer <key> |
| Key 已到期或已停止使用 | 在主控台檢查狀態並建立替代 Key |
| 超出預算或模型範圍 | 檢查 Key 策略和目前模型 |
| 來源不符合限制 | 核對應用程式的實際出口位址 |
第一次接入請先完成快速開始。