Skip to main content
管理 API 金鑰提供一種以程式化方式管理模型 API 金鑰完整生命週期的方法。它專為企業團隊、SaaS 平台與自動化系統設計,使其無需依賴手動控制台操作即可建立、分發、輪換、啟用、停用或撤銷金鑰。 管理 API 金鑰是管理憑證,僅限於金鑰管理操作。它們無法用於呼叫模型推論或補全端點。

1. 概覽

管理 API 金鑰適用於以下情境:
  • 為不同的客戶、專案或環境發行各自獨立的模型 API 金鑰
  • 對下游的模型 API 金鑰套用使用限制與自動重置週期
  • 以程式化方式輪換、停用或撤銷金鑰
  • 在 SaaS、多租戶與注重合規的工作流程中,強制實施最小權限的金鑰管理
核心能力:
  • 對金鑰管理操作進行嚴格的權限隔離
  • 模型 API 金鑰的完整生命週期自動化
  • 可設定的使用限制與重置週期
  • 專為伺服器端服務、內部工具與自動化佈建工作流程設計

2. API 介面與驗證邊界

金鑰管理分為兩個 API 介面,各自擁有獨立的驗證模式: 重要事項:
  • 管理 API 金鑰僅可用於 /api/v1/model-router/keys
  • 管理 API 金鑰無法用於 /v1/management-keys
  • /v1/management-keys 僅支援 JWT 驗證
  • 完整的金鑰密鑰僅在建立時回傳一次,之後無法再次取得

3. 基本規則

  • 每個帳戶最多可建立 10 個管理 API 金鑰
  • 管理 API 金鑰建立後即立即啟用
  • 完整的管理 API 金鑰密鑰僅回傳一次
  • 後續的列表與詳細資料回應僅會回傳遮蔽後的金鑰值
  • 模型 API 金鑰目前採用軟刪除而非永久刪除

4. 基礎網址

公開 API 的基礎網址為:
本文件中使用的路由前綴:

5. 建立管理 API 金鑰

在使用管理 API 之前,請先在 DGrid 控制台中建立一個管理 API 金鑰:
1

開啟「管理 API 金鑰」頁面

2

點擊「建立」

3

輸入金鑰名稱

4

完成所需的安全驗證

5

建立後立即複製並安全儲存金鑰

若您在自己的介面中提供此流程,請明確告知使用者該密鑰僅顯示一次,應立即儲存。

6. 身分驗證

本文件涵蓋兩種驗證模式:
  • /v1/management-keys 下的端點需要 JWT
  • /api/v1/model-router/keys 下的端點需要管理 API 金鑰
呼叫 /api/v1/model-router/keys 端點時請使用以下標頭:

7. 管理 API 金鑰生命週期端點

以下端點用於建立、檢視、更新、啟用、停用與刪除管理 API 金鑰。所有端點皆需要 JWT 驗證。 建立回應範例:
備註:
  • key 僅在建立時回傳一次
  • keyPreview 為遮蔽後的顯示值

8. 使用管理 API 金鑰管理模型 API 金鑰

本節中的所有端點皆使用:

8.1 請求欄位

目前實作支援在建立或更新模型 API 金鑰時使用以下欄位: 備註:
  • 若您熟悉 OpenRouter 的 limit_reset,在目前 DGrid 實作中最接近的等效欄位是 cycle
  • expiredAt 應使用 ISO 8601 UTC 時間戳格式,例如 2026-12-31T23:59:59Z

8.2 列出金鑰

  • 方法:GET
  • 路徑:/api/v1/model-router/keys
  • 查詢參數:
    • page:頁碼,預設為 1
    • size:每頁數量,預設為 20,最大為 100
實作備註:
  • 分頁使用 pagesize,而非 limitoffset
  • 目前不支援名稱的部分匹配搜尋
  • 目前不支援 disabled 篩選
請求範例:
回應範例:
欄位說明:
  • key:遮蔽後的 API 金鑰值
  • usageInCycle:本週期內的使用量
  • usageInTotal:累計使用量
  • enabled:目前的啟用狀態
  • groupName:群組名稱

8.3 建立模型 API 金鑰

  • 方法:POST
  • 路徑:/api/v1/model-router/keys
請求範例:
請求內容範例:
回應範例:
備註:
  • key 是完整的 API 金鑰值,僅回傳一次
  • 請立即將其儲存在安全的密鑰管理系統中

8.4 取得金鑰詳細資料

  • 方法:GET
  • 路徑:/api/v1/model-router/keys/{id}
實作備註:
  • 目前實作使用 id(UUID),而非 key_hash
請求範例:
回應範例:

8.5 更新模型 API 金鑰

  • 方法:PUT
  • 路徑:/api/v1/model-router/keys/{id}
目前支援更新的欄位:
  • name
  • limit
  • cycle
  • groupId
請求範例:
請求內容範例:
實作備註:
  • 目前的更新方法為 PUT,而非 PATCH

8.6 停用模型 API 金鑰

  • 方法:POST
  • 路徑:/api/v1/model-router/keys/{id}/disablement
請求範例:
停用後,該 API 金鑰將無法再用於模型呼叫。

8.7 啟用模型 API 金鑰

  • 方法:POST
  • 路徑:/api/v1/model-router/keys/{id}/enablement
請求範例:

8.8 刪除模型 API 金鑰

  • 方法:DELETE
  • 路徑:/api/v1/model-router/keys/{id}
請求範例:
實作備註:
  • 目前的刪除為軟刪除,而非實體刪除

9. 範例用法

10. HTTP 狀態碼與錯誤碼

11. 標準回應格式

成功的回應使用以下格式:
備註:
  • 成功的請求會回傳 HTTP 200
  • 建立操作的回應可能在 data 中包含完整的密鑰
  • 列表與詳細資料端點通常回傳遮蔽後的金鑰值
  • 管理 API 金鑰與模型 API 金鑰的完整密鑰皆僅回傳一次