修改 API Key

PATCH /api/open/v1/keys/:id

請求參數

只更新請求主體中出現的欄位，未出現的欄位保持不變。至少需要一個可修改欄位：空請求主體、null 或 {} 回傳 400。

參數	位置	類型	必填	說明
id	path	integer	是	Key ID，正整數
name	body	string	否	名稱，去除首尾空白後不能為空，最長 50 個字元（按字元計，不是位元組）
status	body	integer	否	1 啟用、2 停用；其他取值回傳 400（3 / 4 由系統自動設定）
expired_time	body	integer	否	過期時間，unix 秒；0 / -1 表示永不過期
remain_amount	body	number	否	可用金額，站點幣別，兩位小數；不能為負數且不能超過上限
unlimited	body	boolean	否	是否無限額度
model_limits_enabled	body	boolean	否	是否啟用模型白名單
model_limits	body	string	否	允許的模型，以半形逗號分隔
allow_ips	body	string	否	允許的 IP，以換行分隔；空字串表示不限制

status 只接受 1（啟用）或 2（停用）。啟用要求本次更新後 Key 可用：未過期（expired_time 為 -1 或在未來）且無限額度或 remain_amount > 0，否則回傳 400。可以在同一請求中一起傳，如 {"status": 1, "expired_time": 1767225600}。停用不限制原狀態；顯式傳 status 優先於自動恢復。

請求範例

為額度已用盡的 Key 補充額度（Key 會自動恢復為啟用狀態）：

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"remain_amount": 20.00}'

延長有效期限：

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expired_time": 1767225600}'

停用 Key（在重新啟用前，用它發起的請求都會被拒絕）：

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 2}'

重新啟用，並在同一請求中延長有效期，確保啟用後可用：

curl -X PATCH https://www.routeapi.ai/api/open/v1/keys/12 \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": 1, "expired_time": 1767225600}'

回應範例

回傳更新後的 Key 物件，key 為遮罩值：

{
  "success": true,
  "message": "",
  "data": {
    "id": 12,
    "name": "bot",
    "key": "sk-abcd**********wxyz",
    "status": 1,
    "created_time": 1729000000,
    "accessed_time": 1729000000,
    "expired_time": -1,
    "remain_amount": 20.00,
    "unlimited": false,
    "used_amount": 10.00,
    "model_limits_enabled": false,
    "model_limits": "",
    "allow_ips": ""
  }
}

欄位說明見 Key 物件。

錯誤

HTTP	code	情境
400	invalid_request	id 不是正整數，或請求主體不是合法 JSON
400	invalid_request	請求主體為空、null 或沒有任何可修改欄位
400	invalid_request	status 不是 1 或 2（3 / 4 由系統自動設定）
400	invalid_request	Key 仍處於過期或用盡狀態時傳 status: 1；需延長 expired_time、補足 remain_amount 或改為無限額度（可在同一請求中一起傳）
400	invalid_request	名稱超過 50 個字元，或 remain_amount 為負數、超過上限
400	invalid_request	expired_time 不是未來時間（且不是 0 / -1），或超出 9999-12-31
400	invalid_request	對無限額度 Key 單獨傳 remain_amount，或把無限額度 Key 改為有限額度時未傳 remain_amount
404	not_found	Key 不存在或不屬於你

其他通用錯誤碼見 開放平台 API 錯誤。

說明

• 單獨傳 remain_amount：對有限額度 Key 直接生效；對無限額度 Key 回傳 400，需要同時傳 "unlimited": false。
• "unlimited": false 且未傳 remain_amount：對無限額度的 Key 回傳 400（避免餘額被清零）；本來就是有限額度的 Key 保持原餘額不變。
• 已過期（3）或已用盡（4）的 Key，在本次更新後若變為可用（延長 expired_time、補足 remain_amount、改為無限額度），會自動恢復為啟用（1）。自動恢復只在本次請求沒有傳 status 時生效。
• 2 是你手動停用的狀態，不會自動恢復，需要傳 status: 1 重新啟用。Key 不在 1 狀態時，用它呼叫模型介面會被拒絕。
• 先完成全部驗證再一次性寫入：任一欄位驗證失敗都回傳 400，且不會修改任何欄位。
• 透過開放平台 API 修改 Key 會記錄稽核日誌。