更新 API Key | ToAPIs Documentation

PATCH

/api/v1/api-keys/{api_key_id}

中國大陸用戶請注意: 中國大陸用戶請使用 https://api.toapis.cn 作為接口地址 (Base URL). 文檔示例中的 https://api.toapis.com 請替換為 https://api.toapis.cn.

使用說明

修改指定 Key 的設定, 用於調整名稱, 限額, 狀態或到期時間等. 請求主體至少要包含一個欄位; 支援名稱, 模型白名單, 日/月限額, unlimited, 剩餘額度, 狀態和到期時間, 未傳入的欄位保持原值.

啟用與狀態

只修改設定不會自動啟用 Key.
同一請求中明確傳 status=enabled 時, 會按更新後的到期時間, unlimited 和剩餘額度一起校驗: 已到期或有限額度已耗盡的 Key 無法啟用, 回傳 409.
已撤銷的 Key 回傳 404.
不傳 status 時持久化狀態不變: disabled/expired/exhausted 不會因其他欄位更新而自動恢復; enabled Key 的讀取態由額度和到期時間派生, 更新後可能恢復為 enabled.

校驗與寫入

金額欄位校驗規則與建立介面相同: 不接受 JSON 數字或無法精確換算的值.
model_limits 傳 [] 清除模型限制; 日/月限額傳 null 或 "0" 清除限制, 但不會重置已用計數.
設定 remaining_credits 會覆蓋資料庫中已儲存的剩餘額度, 之後的扣費與退款以新值為基準繼續增減; 已產生但尚未寫入資料庫的批次扣費, 之後仍會照常套用.
更新不會改變累計用量或帳戶餘額.
任一欄位校驗失敗時整個請求不寫入, 不會產生部分更新; 更新在交易中按最終設定整體校驗, 只寫入明確傳入的欄位.
快取失效和處理中請求的生效邊界與既有行為一致.

驗證

Authorizationstring請求頭必填

系統存取權杖, 格式為 Bearer YOUR_SYSTEM_ACCESS_TOKEN. 不接受模型 Key, 不需要 X-User-Id. 共用規則見接入方式.

請求參數

api_key_idstring路徑必填

自有一般模型 Key 的十進位 ID 字串, 不是 sk- 密鑰.

非空主體要求 Content-Type: application/json, 上限 16384 位元組. 頂層須為 JSON 物件, 拒絕未知或重複欄位及查詢參數. 寫入主體有 10 秒讀取期限.

statusstring請求體

僅接受 enabled 或 disabled. expired, exhausted, deleted 是唯讀狀態.

expires_atstring | null請求體

未來的 RFC 3339 時間, 小數秒向上取整. null 或建立時省略表示永不到期; 更新時省略保持原值.

namestring請求體

名稱, 去首尾空白後非空, 最多 50 UTF-8 位元組. 省略保持原值.

model_limitsarray請求體

取代整個模型白名單. [] 清除限制, null 不合法. 單項去空白後非空且不含逗號, 按首次出現去重, 拼接後最多 1024 UTF-8 位元組.

daily_limit_creditsstring | null請求體

每日 credits 上限. null 或字串 "0" 表示不限額.

monthly_limit_creditsstring | null請求體

每月 credits 上限. null 或字串 "0" 表示不限額.

unlimitedboolean請求體

布林值, 不接受 null. 切回 false 且省略 remaining_credits 時, 沿用資料庫中已儲存的額度快照, 該額度可能已耗盡. 不自動啟用 Key.

remaining_creditsstring | null請求體

設定剩餘額度絕對值, 不是追加. 最終 unlimited=false 時只接受非負十進位金額字串; true 時只允許省略或 null. 省略時保持已儲存的額度不變; null 不會清除無限 Key 已儲存的額度.

allow_ipsarray請求體

只限制此模型 API Key 的來源 IP 白名單. 字串陣列, 支援單個 IPv4/IPv6 位址; 去首尾空白, 統一格式並去重. [] 清除限制, null 或無效位址回傳 400. 不支援 CIDR, 主機名稱, 連接埠或 IPv6 zone. PATCH 省略時保留原值.

請求範例

請求示例

curl --request PATCH \
  --url 'https://api.toapis.com/api/v1/api-keys/43' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"status": "disabled"}'

import requests

response = requests.patch(
    "https://api.toapis.com/api/v1/api-keys/43",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={'status': 'disabled'},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys/43", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"status": "disabled"}),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

回應欄位

範例使用虛構資料. Key 中繼資料見取得 API Key 詳情, 共用回應與錯誤處理見接入方式.

回應範例

響應示例

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****xyz9",
    "status": "disabled",
    "created_at": "2026-11-01T08:00:00Z",
    "expires_at": "2027-01-01T00:00:00Z",
    "unlimited": false,
    "remaining_credits": "500",
    "daily_limit_credits": null,
    "monthly_limit_credits": null,
    "model_limits": [],
    "allow_ips": []
  }
}