> ## 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-ключи с квотой, сроком действия и списком моделей через /api/token/, затем показывайте, обновляйте, отключайте и удаляйте их из своего кода.

API управления токенами делает то же, что страница «Токены» в консоли, но из вашего кода. Обычно его используют, чтобы автоматически выдавать каждому клиенту ключ с лимитом или отключать пачку ключей после завершения проекта. Вызовы по таким ключам списываются с баланса вашего аккаунта.

| Параметр | Значение |
| - | - |
| Префикс эндпоинтов | `https://api.laozhang.ai/api/token/` |
| Аутентификация | AccessToken аккаунта; см. [API баланса](https://docs.laozhang.ai/ru/api-capabilities/balance-query.md) |
| Квота | 500 000 квоты = 1 USD |
| Формат ответа | `{"success": true, "message": "", "data": ...}` |

> [!WARNING]
>
> **AccessToken даёт полный контроль над аккаунтом. Храните его только на сервере.**
>
> * Не передавайте его в браузер или приложение и не отдавайте клиенту. Клиенты получают только API-ключи, которые вы для них создали.
> * Неверный токен возвращает HTTP 200 с `success: false`, поэтому проверяйте `success` в каждом вызове.

## Эндпоинты

| Действие | Запрос |
| - | - |
| Список ключей | `GET /api/token/?p=0` |
| Поиск по имени | `GET /api/token/search?keyword=NAME&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`; другие группы описаны в разделе [Тарификация и цены](https://docs.laozhang.ai/ru/pricing.md) |
| `billing_type` | integer | Режим оплаты: `4` — сначала по использованию (рекомендуется), `1` — оплата по использованию, `2` — оплата за вызов |
| `models` | string | Список разрешённых моделей: ID через запятую; пустая строка разрешает все модели |
| `remark` | string | Необязательная заметка |

Поле `billing_type` определяет, какие модели ключ может вызывать. Ключи с оплатой по использованию вызывают только такие модели, ключи с оплатой за вызов — только модели за вызов, а ключи «сначала по использованию» (в консоли — 按量优先) вызывают оба типа. Три режима объяснены в разделе [Тарификация и цены](https://docs.laozhang.ai/ru/pricing.md).

## Создание и показ ключа

Скрипт создаёт ключ с лимитом 5 USD, сроком действия 30 дней и двумя разрешёнными моделями, а затем показывает полный ключ. Нужна библиотека `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-ключ моделей (`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 USD
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}")
```

Изменения вступают в силу сразу:

* Отключённый или удалённый ключ при вызове модели получает HTTP 401 `Invalid token.`
* Модель вне списка разрешённых возвращает HTTP 403 с сообщением, что токену нельзя использовать эту модель.

## Ошибки

| Симптом | Причина и решение |
| - | - |
| 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" | Ключ удалён или принадлежит другому аккаунту |

## Частые вопросы

### С чьего баланса списывается плата за ключ клиента?

С вашего. Задайте `remain_quota` каждого ключа как предел расходов. Достигнув предела, ключ перестаёт работать и не может тратить остаток вашего баланса.

### Как узнать, сколько потратил каждый ключ?

Поле `used_quota` в списке и в карточке ключа — это его суммарный расход. Для разбивки по времени или модели используйте [API журнала вызовов](https://docs.laozhang.ai/ru/api-capabilities/log-query.md) с параметром `token_name`.

### Я задал `model_limits`, но поле игнорируется. Почему?

Список разрешённых моделей читается только из `models`. Передайте в него ID моделей одной строкой через запятую.

## Связанные материалы

* Получение AccessToken и проверка баланса: [API баланса](https://docs.laozhang.ai/ru/api-capabilities/balance-query.md)
* Выгрузка записей вызовов по ключу: [API журнала вызовов](https://docs.laozhang.ai/ru/api-capabilities/log-query.md)
* Создание ключей и белые списки IP в консоли: [Создание, хранение, ротация и отзыв API-ключей](https://docs.laozhang.ai/en/faq/token-management.md)


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