建立 API Key | ToAPIs Documentation

POST

/api/v1/api-keys

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

使用說明

建立一個新的模型 Key, 用於呼叫生成介面. 成功時回傳 HTTP 201 和完整密鑰: 密鑰只在該回應中出現一次, 後續 GET 不再回傳, 請立即儲存. 新 Key 使用帳戶的基礎分組, 不能指定分組, 跨分組重試或 Webhook 設定. 初始額度只是該 Key 的呼叫上限, 不會從帳戶餘額中預扣.

金額欄位只接受非負十進位字串, 且必須能精確換算為內部使用的整數額度單位, 不會自動截斷小數. 每個帳戶最多保留 10000 個未刪除的 Key, 達到上限回傳 409 (code=13004). 建立不是冪等操作: 回應遺失時先查詢清單確認是否已建立成功, 不要直接重試; 已建立但未儲存的密鑰可以透過輪替重新取得.

驗證

Authorizationstring請求頭必填

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

請求參數

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

namestring請求體必填

去除首尾空白後必填, 最多 50 UTF-8 位元組.

expires_atstring | null請求體

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

unlimitedboolean請求體預設值: false

預設 false, 不接受 null. true 時 remaining_credits 只能省略或為 null, 給出值回傳 400.

remaining_creditsstring請求體預設值: 0

初始剩餘 credits, 預設字串 "0".

daily_limit_creditsstring | null請求體

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

monthly_limit_creditsstring | null請求體

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

model_limitsarray請求體預設值:

模型 ID 陣列, 預設 []. 非空時啟用限制; 項目去空白後須非空且不含逗號, 依首次出現去重, 拼接後最多 1024 UTF-8 位元組.

allow_ipsarray請求體預設值:

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

請求範例

請求示例

curl --request POST \
  --url 'https://api.toapis.com/api/v1/api-keys' \
  --header 'Authorization: Bearer YOUR_SYSTEM_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"name": "Example Key", "expires_at": "2027-01-01T00:00:00Z", "unlimited": false, "remaining_credits": "500", "daily_limit_credits": null, "monthly_limit_credits": null, "model_limits": ["example-image-model"]}'

import requests

response = requests.post(
    "https://api.toapis.com/api/v1/api-keys",
    headers={"Authorization": "Bearer YOUR_SYSTEM_ACCESS_TOKEN"},
    json={'name': 'Example Key', 'expires_at': '2027-01-01T00:00:00Z', 'unlimited': False, 'remaining_credits': '500', 'daily_limit_credits': None, 'monthly_limit_credits': None, 'model_limits': ['example-image-model']},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.toapis.com/api/v1/api-keys", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_SYSTEM_ACCESS_TOKEN", "Content-Type": "application/json" },
  body: JSON.stringify({"name": "Example Key", "expires_at": "2027-01-01T00:00:00Z", "unlimited": false, "remaining_credits": "500", "daily_limit_credits": null, "monthly_limit_credits": null, "model_limits": ["example-image-model"]}),
  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 詳情, 共用回應與錯誤處理見接入方式.

data.keystring

完整密鑰, 已含 sk- 前綴, 只在本次建立或輪替回應中回傳.

回應範例

響應示例

{
  "code": 0,
  "message": "",
  "data": {
    "id": "43",
    "name": "Example Key",
    "key_hint": "****xyz9",
    "status": "enabled",
    "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,
    "key": "sk-example00000000000000000000000000000000000000xyz9",
    "model_limits": [
      "example-image-model"
    ],
    "allow_ips": []
  }
}