文件
控制台
控制台 API

API 金鑰

Markdown

方法、請求欄位與回應。

完整指南

本區共有 5 個方法。開啟方法即可查看存取條件、請求欄位與回應。

方法與路徑說明存取條件
GET /api/v1/keys清單 — API 金鑰控制台 token
POST /api/v1/keys建立 API 金鑰控制台 token
DELETE /api/v1/keys/:id刪除 — API 金鑰控制台 token
GET /api/v1/keys/:id依識別碼取得 — API 金鑰控制台 token
PUT /api/v1/keys/:id修改 API 金鑰控制台 token
GET /api/v1/keys —清單 — API 金鑰

存取條件：控制台 token

GET/api/v1/keys
讀取；ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/keys" \
  -H "Authorization: Bearer $TOKEN"

查詢參數

欄位類型必填驗證／說明
sort_bystring否; 預設值：created_at
sort_orderstring否; 預設值：desc
searchstring否
statusstring否
pageinteger否; 預設值：1；正數；page_size/limit <=1000
page_sizeinteger否; 預設值：20；正數；page_size/limit <=1000
limitinteger否; 預設值：20；正數；page_size/limit <=1000

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述：APIKey。欄位與型別請見「資料結構描述」頁面。

回應結構描述，欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "PLACEHOLDER_ID (integer)",
        "user_id": "PLACEHOLDER_USER_ID (integer)",
        "key": "PLACEHOLDER_KEY (string)",
        "name": "PLACEHOLDER_NAME (string)",
        "status": "PLACEHOLDER_STATUS (string)",
        "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
        "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
        "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
        "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
        "quota": "PLACEHOLDER_QUOTA (number)",
        "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
        "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
        "created_at": "PLACEHOLDER_CREATED_AT (string)",
        "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
        "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
        "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
        "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
        "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
        "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
        "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
        "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
        "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
        "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
        "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
        "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
        "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
        "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
        "user": "PLACEHOLDER_USER (object)"
      }
    ],
    "total": "PLACEHOLDER_TOTAL (integer)",
    "page": "PLACEHOLDER_PAGE (integer)",
    "page_size": "PLACEHOLDER_PAGE_SIZE (integer)",
    "pages": "PLACEHOLDER_PAGES (integer)"
  }
}

注意事項：所有個人資料與物件，皆限於 JWT 主體的範圍。

注意事項：回應包含機密的 key，請勿公開實際值。

POST /api/v1/keys —建立 API 金鑰

存取條件：控制台 token

POST/api/v1/keys

JSON／表單欄位

欄位類型必填驗證／說明
namestring是required
custom_keystring否; 自訂金鑰值，選填；可為 null
ip_whitelistarray否; 允許的 IP 清單
ip_blacklistarray否; 禁止的 IP 清單
quotanumber否; 金鑰的支出上限，以 USD 計價；可為 null
expires_in_daysinteger否; 有效期限，以天為單位；可為 null
rate_limit_5hnumber否; 可為 null
rate_limit_1dnumber否; 可為 null
rate_limit_7dnumber否; 可為 null
請求主體範本
{
  "name": "PLACEHOLDER_NAME (string)",
  "custom_key": "PLACEHOLDER_CUSTOM_KEY (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_in_days": "PLACEHOLDER_EXPIRES_IN_DAYS (integer)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)"
}

PLACEHOLDER 表示您的輸入及其型別。請替換值，並只保留需要的選填欄位；不要將字串標記當成數字、boolean、物件或陣列傳送。

請求結構描述：CreateAPIKeyRequest

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述：APIKey。欄位與型別請見「資料結構描述」頁面。

回應結構描述，欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

注意事項：所有個人資料與物件，皆限於 JWT 主體的範圍。

注意事項：此操作會變更狀態，或繼續一次性授權流程；範例僅說明介面契約，不會執行。

注意事項：支援 Idempotency-Key；重複請求會傳回已保存的回應，並附帶 X-Idempotency-Replayed。

注意事項：回應包含機密的 key，請勿公開實際值。

DELETE /api/v1/keys/:id —刪除 — API 金鑰

存取條件：控制台 token

DELETE/api/v1/keys/:id

路徑參數

欄位類型必填驗證／說明
idinteger是

不需要請求主體。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應結構描述，欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}

注意事項：所有個人資料與物件，皆限於 JWT 主體的範圍。

注意事項：此操作會變更狀態，或繼續一次性授權流程；範例僅說明介面契約，不會執行。

注意事項：回應包含機密的 key，請勿公開實際值。

GET /api/v1/keys/:id —依識別碼取得 — API 金鑰

存取條件：控制台 token

GET/api/v1/keys/:id
讀取；ID 取自您先前的回應
curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"

路徑參數

欄位類型必填驗證／說明
idinteger是

不需要請求主體。請在 URL 中傳入上述參數。

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述：APIKey。欄位與型別請見「資料結構描述」頁面。

回應結構描述，欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

注意事項：所有個人資料與物件，皆限於 JWT 主體的範圍。

注意事項：回應包含機密的 key，請勿公開實際值。

PUT /api/v1/keys/:id —修改 API 金鑰

存取條件：控制台 token

PUT/api/v1/keys/:id

路徑參數

欄位類型必填驗證／說明
idinteger是

JSON／表單欄位

欄位類型必填驗證／說明
namestring否
statusstring否omitempty,oneof=active inactive
ip_whitelistarray否; 允許的 IP：null 不會變更清單，空陣列會清空清單；可為 null
ip_blacklistarray否; 禁止的 IP：null 不會變更清單，空陣列會清空清單；可為 null
quotanumber否; 金鑰的支出上限，以 USD 計價；0 表示不限額；可為 null
expires_atstring否; 有效期限的結束時間，採 ISO 8601 格式；可為 null
reset_quotaboolean否; 重設支出上限中已使用的額度；可為 null
rate_limit_5hnumber否; 可為 null
rate_limit_1dnumber否; 可為 null
rate_limit_7dnumber否; 可為 null
reset_rate_limit_usageboolean否; 重設各時間視窗中已使用的額度；可為 null
請求主體範本
{
  "name": "PLACEHOLDER_NAME (string)",
  "status": "PLACEHOLDER_STATUS (string)",
  "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
  "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
  "quota": "PLACEHOLDER_QUOTA (number)",
  "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
  "reset_quota": "PLACEHOLDER_RESET_QUOTA (boolean)",
  "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
  "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
  "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
  "reset_rate_limit_usage": "PLACEHOLDER_RESET_RATE_LIMIT_USAGE (boolean)"
}

PLACEHOLDER 表示您的輸入及其型別。請替換值，並只保留需要的選填欄位；不要將字串標記當成數字、boolean、物件或陣列傳送。

請求結構描述：UpdateAPIKeyRequest

回應

JSON 回應包含 code、message與data。data 的內容請見下方結構描述。

回應資料的結構描述：APIKey。欄位與型別請見「資料結構描述」頁面。

回應結構描述，欄位值僅為示例
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "PLACEHOLDER_ID (integer)",
    "user_id": "PLACEHOLDER_USER_ID (integer)",
    "key": "PLACEHOLDER_KEY (string)",
    "name": "PLACEHOLDER_NAME (string)",
    "status": "PLACEHOLDER_STATUS (string)",
    "ip_whitelist": "PLACEHOLDER_IP_WHITELIST (array)",
    "ip_blacklist": "PLACEHOLDER_IP_BLACKLIST (array)",
    "last_used_at": "PLACEHOLDER_LAST_USED_AT (string)",
    "last_used_ip": "PLACEHOLDER_LAST_USED_IP (string)",
    "quota": "PLACEHOLDER_QUOTA (number)",
    "quota_used": "PLACEHOLDER_QUOTA_USED (number)",
    "expires_at": "PLACEHOLDER_EXPIRES_AT (string)",
    "created_at": "PLACEHOLDER_CREATED_AT (string)",
    "updated_at": "PLACEHOLDER_UPDATED_AT (string)",
    "current_concurrency": "PLACEHOLDER_CURRENT_CONCURRENCY (integer)",
    "rate_limit_5h": "PLACEHOLDER_RATE_LIMIT_5H (number)",
    "rate_limit_1d": "PLACEHOLDER_RATE_LIMIT_1D (number)",
    "rate_limit_7d": "PLACEHOLDER_RATE_LIMIT_7D (number)",
    "usage_5h": "PLACEHOLDER_USAGE_5H (number)",
    "usage_1d": "PLACEHOLDER_USAGE_1D (number)",
    "usage_7d": "PLACEHOLDER_USAGE_7D (number)",
    "window_5h_start": "PLACEHOLDER_WINDOW_5H_START (string)",
    "window_1d_start": "PLACEHOLDER_WINDOW_1D_START (string)",
    "window_7d_start": "PLACEHOLDER_WINDOW_7D_START (string)",
    "reset_5h_at": "PLACEHOLDER_RESET_5H_AT (string)",
    "reset_1d_at": "PLACEHOLDER_RESET_1D_AT (string)",
    "reset_7d_at": "PLACEHOLDER_RESET_7D_AT (string)",
    "user": "PLACEHOLDER_USER (object)"
  }
}

注意事項：所有個人資料與物件，皆限於 JWT 主體的範圍。

注意事項：此操作會變更狀態，或繼續一次性授權流程；範例僅說明介面契約，不會執行。

注意事項：回應包含機密的 key，請勿公開實際值。

注意事項：若金鑰仍有尚未完成且已保留金額的請求，就不能降低或重設其支出上限。請只傳入要變更的欄位。

還有疑問嗎？請提供 Request ID與問題描述，我們會協助釐清。聯絡支援
登入註冊控制台
方案