令牌管理 API

介面概述

令牌管理介面讓你用程式完成 API Key 的全生命週期管理，不必逐個在控制台點選。最常見的場景是批次發放：給團隊成員、給下游客戶、給不同專案各發一把 Key，並分別限制能花多少錢、能用哪些模型、用到什麼時候。

額度限制

remain_quota 設定這把 Key 最多能消費多少

模型限制

models 設定白名單，呼叫名單外的模型直接被拒

有效期限制

expired_time 設定到期時間，到點自動失效

只需要建一兩把 Key 的話，直接用控制台更快，見如何建立 KEY。本介面面向需要自動化發放、定期輪換、或把 Key 管理接入自有系統的場景。

如何獲取系統令牌

令牌管理介面用系統令牌認證，與 API Key 不是一回事。

訪問控制台

訪問 api.apiyi.com/account/profile 個人中心頁面

找到系統令牌

在頁面最下方找到「賬號選項 - 系統令牌」部分

生成 AccessToken

輸入當前的賬戶密碼後，會得到一個 AccessToken，該金鑰可用於後續介面的查詢資料

系統令牌可以建立和刪除 API Key，請像保管賬號密碼一樣保管它。系統令牌本身不能呼叫模型（拿去請求 /v1/chat/completions 會被拒絕），但它能創建出可以呼叫模型的 API Key。因此洩漏系統令牌的後果比洩漏單把 API Key 嚴重得多 —— 請存進金鑰管理工具而不是寫在程式碼裡，不要提交進程式碼倉庫，並定期輪換。

端點一覽

所有端點的認證方式相同：Authorization 請求頭填系統令牌裸值，不加 Bearer 字首。

方法	路徑	用途
`GET`	`/api/token/?p=0&page_size=100`	列出本賬號所有令牌
`GET`	`/api/token/{id}`	查詢單個令牌
`POST`	`/api/token/`	建立令牌，響應直接返回明文 key
`PUT`	`/api/token/`	更新令牌（需傳完整物件）
`PUT`	`/api/token/?status_only=true`	只切換啟用/停用狀態
`DELETE`	`/api/token/{id}`	刪除令牌

基礎地址為 https://api.apiyi.com。

建立令牌

請求示例

export APIYI_SYS_TOKEN='YOUR_SYSTEM_TOKEN'

curl --compressed -s -X POST 'https://api.apiyi.com/api/token/' \
  -H "Authorization: $APIYI_SYS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "team-alice",
    "remain_quota": 500000,
    "unlimited_quota": false,
    "group": "default",
    "models": "gpt-5.6,deepseek-chat",
    "expired_time": -1
  }'

請求欄位

欄位	型別	說明
`name`	String	令牌名稱，用於自己識別用途
`remain_quota`	Integer	額度上限（額度數），500,000 = $1.00
`unlimited_quota`	Boolean	是否不限額度；預設為 `false`
`group`	String	令牌繫結的分組識別符號，如 `default`
`models`	String	模型白名單，逗號分隔；不傳表示不限
`expired_time`	Integer	過期時間戳（Unix 秒），`-1` 表示永不過期

unlimited_quota 預設為 false，而 remain_quota 預設為 0 —— 兩者一起預設時會建出一把額度為 0、無法使用的令牌。要麼顯式給 remain_quota 賦值，要麼把 unlimited_quota 設為 true。

模型白名單請使用 models 欄位。響應結構裡還存在 model_limits、model_limits_enabled、allow_ips 三個欄位，傳入它們不會報錯（介面仍返回 200），但當前不會生效 —— 回讀時這些欄位仍為空。需要限制可用模型請使用 models，需要限制來源 IP 請在自己的服務側實現。

響應示例

{
  "success": true,
  "message": "",
  "data": {
    "id": 119431,
    "user_id": 80778,
    "key": "K1RPzapuXLfBU4kDC5D9C0E70b1841AeAa542186B2F54b75",
    "status": 1,
    "name": "team-alice",
    "group": "default",
    "models": "gpt-5.6,deepseek-chat",
    "remain_quota": 500000,
    "unlimited_quota": false,
    "used_quota": 0,
    "expired_time": -1,
    "created_time": 1785599000
  }
}

響應裡的 key 是明文，且不含 sk- 字首。 實際使用時需要自己拼上字首，即上例中真正的 API Key 是 sk-K1RPzapu…。請在建立時就妥善儲存並分發，不要把包含 key 的響應體留在日誌檔案裡。

批次建立

服務端沒有批次建立介面 —— 在請求體裡傳 count 之類的引數不會生效，仍然只建立一把。批次發放的做法是在客戶端迴圈呼叫建立介面。

Python
Node.js
cURL

import json
import os

import requests

BASE = "https://api.apiyi.com"
HEADERS = {"Authorization": os.environ["APIYI_SYS_TOKEN"],
           "Content-Type": "application/json"}
QUOTA_PER_USD = 500_000


def create_token(name, quota_usd=None, group="default", models=None, days=0):
    """建立一把令牌。quota_usd 為 None 表示不限額度，days 為 0 表示永不過期。"""
    import time
    body = {
        "name": name,
        "group": group,
        "unlimited_quota": quota_usd is None,
        "remain_quota": 0 if quota_usd is None else int(quota_usd * QUOTA_PER_USD),
        "expired_time": -1 if not days else int(time.time()) + days * 86400,
    }
    if models:
        body["models"] = models

    resp = requests.post(f"{BASE}/api/token/", headers=HEADERS, json=body, timeout=30)
    resp.raise_for_status()
    data = resp.json()["data"]
    return {"id": data["id"], "name": data["name"], "key": "sk-" + data["key"]}


if __name__ == "__main__":
    names = ["team-alice", "team-bob", "team-carol"]
    created = [
        create_token(n, quota_usd=1, group="default", models="gpt-5.6", days=30)
        for n in names
    ]
    for row in created:
        print(f"{row['name']:16s} id={row['id']} {row['key']}")

    # 明文 key 只在建立時返回，注意妥善儲存與分發
    with open("keys.json", "w") as f:
        json.dump(created, f, ensure_ascii=False, indent=1)

const BASE = "https://api.apiyi.com";
const HEADERS = {
  Authorization: process.env.APIYI_SYS_TOKEN,
  "Content-Type": "application/json",
};
const QUOTA_PER_USD = 500_000;

async function createToken(name, { quotaUsd = null, group = "default",
                                   models = null, days = 0 } = {}) {
  const body = {
    name,
    group,
    unlimited_quota: quotaUsd === null,
    remain_quota: quotaUsd === null ? 0 : Math.round(quotaUsd * QUOTA_PER_USD),
    expired_time: days ? Math.floor(Date.now() / 1000) + days * 86400 : -1,
  };
  if (models) body.models = models;

  const resp = await fetch(`${BASE}/api/token/`, {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify(body),
  });
  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
  const { data } = await resp.json();
  return { id: data.id, name: data.name, key: `sk-${data.key}` };
}

const names = ["team-alice", "team-bob", "team-carol"];
for (const name of names) {
  const row = await createToken(name, { quotaUsd: 1, models: "gpt-5.6", days: 30 });
  console.log(row.name, row.id, row.key);
}

export APIYI_SYS_TOKEN='YOUR_SYSTEM_TOKEN'

for NAME in team-alice team-bob team-carol; do
  curl --compressed -s -X POST 'https://api.apiyi.com/api/token/' \
    -H "Authorization: $APIYI_SYS_TOKEN" \
    -H 'Content-Type: application/json' \
    -d "{\"name\":\"$NAME\",\"remain_quota\":500000,\"unlimited_quota\":false,\"group\":\"default\",\"expired_time\":-1}" \
    | jq -r '"\(.data.name)\tsk-\(.data.key)"'
done

三重限制怎麼用

額度限制

remain_quota 是這把令牌能消費的額度上限，換算關係與餘額查詢一致：

換算規則

500,000 額度 = $1.00 美金 (USD)

例如給下游客戶發一把最多消費 $10 的 Key，就設 remain_quota: 5000000 且 unlimited_quota: false。用量可以從令牌的 used_quota 欄位讀取。

模型限制

models 是逗號分隔的白名單。設定後，用這把 Key 呼叫名單外的模型會被直接拒絕：

{
  "error": {
    "message": "該令牌無權使用模型：deepseek-chat"
  }
}

返回 HTTP 403，不產生扣費。不傳 models 表示不限制。

有效期限制

expired_time 是 Unix 秒時間戳，-1 表示永不過期。例如發一把 30 天后失效的 Key：

import time
expired_time = int(time.time()) + 30 * 86400

查詢令牌

curl --compressed -s 'https://api.apiyi.com/api/token/?p=0&page_size=100' \
  -H "Authorization: $APIYI_SYS_TOKEN" | jq '.data[] | {id, name, status, remain_quota, used_quota, models}'

關鍵欄位：

欄位	說明
`id`	令牌 ID，更新與刪除時用
`key`	Key 明文（不含 `sk-` 字首）
`status`	`1` = 啟用，`2` = 停用
`remain_quota` / `used_quota`	剩餘 / 已用額度
`unlimited_quota`	是否不限額度
`models`	模型白名單，空表示不限
`expired_time`	過期時間戳，`-1` 表示永不過期

更新令牌

更新介面需要傳完整物件，不是增量更新（patch）。正確做法是：先 GET 拿到令牌的完整物件 → 修改需要變更的欄位 → 把整個物件 PUT 回去。只傳要改的那幾個欄位會把其餘欄位清空。

import os
import requests

BASE = "https://api.apiyi.com"
HEADERS = {"Authorization": os.environ["APIYI_SYS_TOKEN"],
           "Content-Type": "application/json"}

# 1. 取回完整物件
token = requests.get(f"{BASE}/api/token/119431", headers=HEADERS, timeout=30).json()["data"]

# 2. 只改需要變的欄位，其餘原樣保留
token["remain_quota"] = 2_500_000     # 提到 $5
token["models"] = "gpt-5.6,gemini-3-pro"

# 3. 整個物件 PUT 回去
resp = requests.put(f"{BASE}/api/token/", headers=HEADERS, json=token, timeout=30)
print(resp.json()["success"])

停用與刪除

停用（保留記錄）

停用後該 Key 立即失效，再用它呼叫模型會返回 401，但令牌記錄和歷史用量仍然保留。

token = requests.get(f"{BASE}/api/token/119431", headers=HEADERS, timeout=30).json()["data"]
token["status"] = 2      # 1 = 啟用，2 = 停用

requests.put(f"{BASE}/api/token/", headers=HEADERS,
             params={"status_only": "true"}, json=token, timeout=30)

刪除（不可恢復）

curl --compressed -s -X DELETE 'https://api.apiyi.com/api/token/119431' \
  -H "Authorization: $APIYI_SYS_TOKEN"

批次刪除同樣在客戶端迴圈即可：

for token_id in [119431, 119432, 119433]:
    requests.delete(f"{BASE}/api/token/{token_id}", headers=HEADERS, timeout=30)

刪除是不可恢復操作。如果只是想臨時停用，用上面的停用方式，歷史用量記錄會保留下來便於對賬。

常見問題

建立時返回的 key 怎麼直接不能用？

響應裡的 key 不含 sk- 字首，實際使用時需要自己拼上，即 sk- + key 的值。

為什麼我建出來的令牌一呼叫就提示額度不足？

最可能的原因是建立時既沒傳 remain_quota，也沒把 unlimited_quota 設為 true —— 兩者的預設組合會建出一把額度為 0 的令牌。重新建立時顯式指定其中之一即可。

傳了 model_limits 或 allow_ips 為什麼沒有效果？

這兩個欄位（以及 model_limits_enabled）當前不生效，傳入不會報錯但也不會落庫。限制可用模型請使用 models 欄位；限制來源 IP 目前需要在你自己的服務側實現。

能一次建立多把令牌嗎？

服務端沒有批次建立介面，在請求體裡傳 count 之類的引數不會生效。批次發放請在客戶端迴圈呼叫建立介面，參考上面「批次建立」一節的示例。

更新令牌後其他欄位被清空了？

更新介面需要傳完整物件。先 GET 拿到完整物件，改完再整個 PUT 回去，不要只傳要改的那幾個欄位。

停用和刪除有什麼區別？

停用（status: 2）後 Key 立即失效，但令牌記錄與歷史用量保留，可以隨時改回 1 恢復。刪除是不可恢復的，記錄一併移除。臨時停用建議用停用。

怎麼知道每把 Key 各自花了多少錢？

令牌物件的 used_quota 欄位就是這把 Key 的累計消費（÷ 500,000 = 美元）。需要按時間段拆分或看每次呼叫的明細，用日誌查詢 API 的 token_name 引數過濾。

注意事項

系統令牌不是 API Key，兩者不能互換

API Key（sk- 開頭）用於 /v1/* 推理端點
系統令牌（一串不帶字首的字元）用於 /api/* 管理端點

用錯會分別得到 401 與 Invalid token 錯誤。

妥善保管明文 Key建立介面的響應體、以及令牌列表介面的返回，都包含 Key 明文。請注意：

不要把包含 key 的原始響應寫進日誌檔案或提交進程式碼倉庫
分發給團隊成員時使用安全渠道，不要通過聊天群直接傳送
這段明文不帶 sk- 字首，常見的金鑰掃描工具可能掃不出來，不要依賴自動化檢查兜底

操作建議

批次建立時建議在迴圈里加適度間隔，避免瞬時併發過高
給每把 Key 起有意義的 name（如 team-alice、prod-webhook），便於後續在日誌裡按 token_name 歸因
定期輪換：新建 Key → 切流量 → 停用舊 Key 觀察一段時間 → 確認無呼叫後再刪除

產品基礎

基礎 API

圖片 API（官轉）

影片 API（官轉）

多模態理解 API

文本生成

檢索與安全

介面概述

額度限制

模型限制

有效期限制

如何獲取系統令牌

端點一覽

建立令牌

請求示例

請求欄位

響應示例

批次建立

三重限制怎麼用

額度限制

換算規則

模型限制

有效期限制

查詢令牌

更新令牌

停用與刪除

停用（保留記錄）

刪除（不可恢復）

常見問題

注意事項

相關文件

​介面概述

額度限制

模型限制

有效期限制

​如何獲取系統令牌

​端點一覽

​建立令牌

​請求示例

​請求欄位

​響應示例

​批次建立

​三重限制怎麼用

​額度限制

換算規則

​模型限制

​有效期限制

​查詢令牌

​更新令牌

​停用與刪除

​停用（保留記錄）

​刪除（不可恢復）

​常見問題

​注意事項

相關文件

介面概述

如何獲取系統令牌

端點一覽

建立令牌

請求示例

請求欄位

響應示例

批次建立

三重限制怎麼用

額度限制

模型限制

有效期限制

查詢令牌

更新令牌

停用與刪除

停用（保留記錄）

刪除（不可恢復）

常見問題

注意事項