> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laozhang.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 老张API 令牌管理 API：用程序批量创建、禁用和删除 API Key

> 用 AccessToken 调用 /api/token/ 接口，为每个客户或项目发放带额度、有效期和模型白名单的 API Key，并在需要时取回完整密钥、修改、禁用或删除。

令牌管理 API 做的事情和控制台「令牌」页相同，但可以写进程序：例如给每个下游客户自动发一把限额 Key，或在项目结束时批量停用。用这些 Key 调用模型产生的费用，都从你的账户余额扣除。

| 项目 | 内容 |
| - | - |
| 接口前缀 | `https://api.laozhang.ai/api/token/` |
| 认证 | 系统令牌 AccessToken，获取方法见[余额查询 API](/api-capabilities/balance-query#获取-accesstoken) |
| 额度单位 | 50 万额度 = 1 USD |
| 返回格式 | `{"success": true, "message": "", "data": ...}` |

<Warning>
  **AccessToken 拥有账户的全部权限，只放在服务端。**

  * 不要下发到浏览器、App 或交给下游客户；下游只拿到你为他们创建的 API Key。
  * 令牌无效时接口返回 HTTP 200 加 `success: false`，每次都要检查 `success`。
</Warning>

## 接口一览

| 操作 | 请求 |
| - | - |
| 列出令牌 | `GET /api/token/?p=0` |
| 按名称搜索 | `GET /api/token/search?keyword=名称&p=0` |
| 查看单个令牌 | `GET /api/token/{id}` |
| 创建令牌 | `POST /api/token/` |
| 取回完整密钥 | `POST /api/token/{id}/key` |
| 修改令牌 | `PUT /api/token/` |
| 启用或禁用 | `PUT /api/token/?status_only=true` |
| 删除令牌 | `DELETE /api/token/{id}` |

列表和搜索每页 10 条，`p` 从 0 开始。列表里的 `key` 是打码后的值，要拿到能调用模型的完整密钥，用「取回完整密钥」接口。

## 创建字段

| 字段 | 类型 | 说明 |
| - | - | - |
| `name` | string | 令牌名称，便于搜索；过长会被拒绝 |
| `remain_quota` | integer | 可用额度，`500000` 即 1 USD |
| `unlimited_quota` | boolean | `true` 表示不限额度，此时忽略 `remain_quota` |
| `expired_time` | integer | 过期时间，Unix 秒；`-1` 表示永不过期 |
| `group` | string | 令牌分组，通常填 `default`；其他分组名见[计费说明](/pricing) |
| `billing_type` | integer | 计费模式：`4` 按量优先（推荐）、`1` 按量计费、`2` 按次计费 |
| `models` | string | 模型白名单，多个 ID 用英文逗号分隔；空字符串表示不限制 |
| `remark` | string | 备注，可选 |

`billing_type` 决定这把 Key 能调用哪些模型：按量计费只能调按量模型，按次计费只能调按次模型，按量优先两类都能调。三种模式的区别见[计费说明](/pricing)。

## 创建并取回密钥

下面的脚本创建一把额度 5 美元、30 天有效、只能调用两个模型的 Key，再取回完整密钥。需要 `requests`（`python -m pip install requests`）。

```python theme={null}
import os
import time

import requests

BASE = "https://api.laozhang.ai"
HEADERS = {"Authorization": os.environ["LAOZHANG_ACCESS_TOKEN"]}


def call(method, path, **kwargs):
    response = requests.request(method, BASE + path, headers=HEADERS, timeout=30, **kwargs)
    response.raise_for_status()
    payload = response.json()
    if not payload.get("success"):
        raise RuntimeError(f"{path}: {payload.get('message')}")
    return payload.get("data")


created = call("POST", "/api/token/", json={
    "name": "customer-acme",
    "remain_quota": 5 * 500_000,
    "unlimited_quota": False,
    "expired_time": int(time.time()) + 30 * 86400,
    "group": "default",
    "billing_type": 4,
    "models": "gpt-5.4-mini,gemini-3.8-flash",
    "remark": "Acme 试用",
})
token_id = created["id"]

key = call("POST", f"/api/token/{token_id}/key")["key"]
print(token_id, key[:6] + "...")
```

取回的密钥可以直接用作模型调用的 API Key（`Authorization: Bearer <key>`），前面加不加 `sk-` 都能用。把它交给下游前保存到你的密钥系统，之后不要频繁调用取回接口，它有严格的频率限制。

## 修改、禁用和删除

修改时要提交完整的令牌对象：先用 `GET /api/token/{id}` 读出来，改需要的字段，再整体 `PUT`。只提交几个字段，其他字段可能被重置。

```python theme={null}
token = call("GET", f"/api/token/{token_id}")
token.pop("key", None)
token["remain_quota"] += 10 * 500_000   # 追加 10 美元额度
token["models"] = "gpt-5.4-mini,gemini-3.8-flash,deepseek-v4-flash"
call("PUT", "/api/token/", json=token)

call("PUT", "/api/token/?status_only=true", json={"id": token_id, "status": 2})  # 禁用
call("PUT", "/api/token/?status_only=true", json={"id": token_id, "status": 1})  # 重新启用

call("DELETE", f"/api/token/{token_id}")
```

修改和启停立即生效：

* 禁用或删除后，用这把 Key 调用模型返回 HTTP 401 `Invalid token.`。
* 调用白名单以外的模型返回 HTTP 403 `该令牌无权使用模型：<模型 ID>`。

## 错误处理

| 现象 | 原因与处理 |
| - | - |
| HTTP 401，`AUTH_REQUIRED` | 没有带 `Authorization` |
| HTTP 200，`success: false`，access token is invalid | AccessToken 错误或已重新生成 |
| HTTP 403，does not have write permission | 当前令牌只有读取权限，不能创建、修改或删除 |
| `success: false`，令牌名称过长 | 缩短 `name` |
| `GET /api/token/{id}` 返回 record not found | 令牌已删除，或不属于当前账户 |

## 常见问题

### 下游客户用的 Key 会扣谁的钱？

扣你的账户余额。通过 `remain_quota` 给每把 Key 设上限，用完后这把 Key 停止工作，不会继续消耗账户里的其他余额。

### 怎么统计每把 Key 用了多少？

列表和详情里的 `used_quota` 是这把 Key 累计消耗的额度。要按时间或模型拆分，用[日志查询 API](/api-capabilities/log-query) 加 `token_name` 筛选。

### 用了 `model_limits` 字段，为什么没生效？

模型白名单只认 `models` 字段。把允许的模型 ID 用英文逗号连起来写在 `models` 里。

## 相关文档

* 获取 AccessToken 与查询余额：[余额查询 API](/api-capabilities/balance-query)
* 按令牌导出调用记录：[日志查询 API](/api-capabilities/log-query)
* 在控制台创建 Key 与设置 IP 白名单：[API Key 如何创建、保存、轮换和撤销？](/faq/token-management)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.