Source: https://ailoot.ai/docs/zh-hant-tw/cabinet/keys/
Canonical: https://ailoot.ai/docs/zh-hant-tw/cabinet/keys/
Language: zh-hant-tw

[控制台 API](https://ailoot.ai/docs/zh-hant-tw/) 

# API 金鑰

[Markdown](https://ailoot.ai/docs/zh-hant-tw/cabinet/keys/index.md)

方法、請求欄位與回應。

本區共有 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 取自您先前的回應

```bash
curl --fail-with-body "https://ailoot.ai/api/v1/keys" \
  -H "Authorization: Bearer $TOKEN"
```

## 查詢參數

| 欄位 | 類型 | 必填 | 驗證／說明 |
| --- | --- | --- | --- |
| `sort_by` | `string` | 否 | ; 預設值：created\_at |
| `sort_order` | `string` | 否 | ; 預設值：desc |
| `search` | `string` | 否 |  |
| `status` | `string` | 否 |  |
| `page` | `integer` | 否 | ; 預設值：1；正數；page\_size/limit \<=1000 |
| `page_size` | `integer` | 否 | ; 預設值：20；正數；page\_size/limit \<=1000 |
| `limit` | `integer` | 否 | ; 預設值：20；正數；page\_size/limit \<=1000 |

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

## 回應

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

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

回應結構描述，欄位值僅為示例

```json
{
  "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／表單欄位

| 欄位 | 類型 | 必填 | 驗證／說明 |
| --- | --- | --- | --- |
| `name` | `string` | 是 | required |
| `custom_key` | `string` | 否 | ; 自訂金鑰值，選填；可為 null |
| `ip_whitelist` | `array` | 否 | ; 允許的 IP 清單 |
| `ip_blacklist` | `array` | 否 | ; 禁止的 IP 清單 |
| `quota` | `number` | 否 | ; 金鑰的支出上限，以 USD 計價；可為 null |
| `expires_in_days` | `integer` | 否 | ; 有效期限，以天為單位；可為 null |
| `rate_limit_5h` | `number` | 否 | ; 可為 null |
| `rate_limit_1d` | `number` | 否 | ; 可為 null |
| `rate_limit_7d` | `number` | 否 | ; 可為 null |

請求主體範本

```json
{
  "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`。欄位與型別請見「資料結構描述」頁面。

回應結構描述，欄位值僅為示例

```json
{
  "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，請勿公開實際值。

此方法會變更資料。只有在方法標示 Idempotency-Key 時，重新傳送才是安全的。若回應遺失，請先確認操作結果 (例如金鑰清單)，再決定是否重新傳送請求。

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

存取條件：控制台 token

DELETE`/api/v1/keys/:id`

## 路徑參數

| 欄位 | 類型 | 必填 | 驗證／說明 |
| --- | --- | --- | --- |
| `id` | `integer` | 是 |  |

不需要請求主體。

## 回應

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

回應結構描述，欄位值僅為示例

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "message": "VALUE_FROM_RESPONSE"
  }
}
```

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

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

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

此方法會變更資料。只有在方法標示 Idempotency-Key 時，重新傳送才是安全的。若回應遺失，請先確認操作結果 (例如金鑰清單)，再決定是否重新傳送請求。

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

存取條件：控制台 token

GET`/api/v1/keys/:id`

讀取；ID 取自您先前的回應

```bash
curl --fail-with-body "https://ailoot.ai/api/v1/keys/$ID" \
  -H "Authorization: Bearer $TOKEN"
```

## 路徑參數

| 欄位 | 類型 | 必填 | 驗證／說明 |
| --- | --- | --- | --- |
| `id` | `integer` | 是 |  |

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

## 回應

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

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

回應結構描述，欄位值僅為示例

```json
{
  "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`

## 路徑參數

| 欄位 | 類型 | 必填 | 驗證／說明 |
| --- | --- | --- | --- |
| `id` | `integer` | 是 |  |

## JSON／表單欄位

| 欄位 | 類型 | 必填 | 驗證／說明 |
| --- | --- | --- | --- |
| `name` | `string` | 否 |  |
| `status` | `string` | 否 | omitempty,oneof=active inactive |
| `ip_whitelist` | `array` | 否 | ; 允許的 IP：null 不會變更清單，空陣列會清空清單；可為 null |
| `ip_blacklist` | `array` | 否 | ; 禁止的 IP：null 不會變更清單，空陣列會清空清單；可為 null |
| `quota` | `number` | 否 | ; 金鑰的支出上限，以 USD 計價；0 表示不限額；可為 null |
| `expires_at` | `string` | 否 | ; 有效期限的結束時間，採 ISO 8601 格式；可為 null |
| `reset_quota` | `boolean` | 否 | ; 重設支出上限中已使用的額度；可為 null |
| `rate_limit_5h` | `number` | 否 | ; 可為 null |
| `rate_limit_1d` | `number` | 否 | ; 可為 null |
| `rate_limit_7d` | `number` | 否 | ; 可為 null |
| `reset_rate_limit_usage` | `boolean` | 否 | ; 重設各時間視窗中已使用的額度；可為 null |

請求主體範本

```json
{
  "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`。欄位與型別請見「資料結構描述」頁面。

回應結構描述，欄位值僅為示例

```json
{
  "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，請勿公開實際值。

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

此方法會變更資料。只有在方法標示 Idempotency-Key 時，重新傳送才是安全的。若回應遺失，請先確認操作結果 (例如金鑰清單)，再決定是否重新傳送請求。

還有疑問嗎？請提供 Request ID與問題描述，我們會協助釐清。[聯絡支援](mailto:support@ailoot.ai)

## Ailoot · 公司及其專案組合





Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。





公司及其專案組合：數百萬客戶，每月銷售額達數十億。





Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。