Обзор API
API управления токенами позволяет программно управлять полным жизненным циклом ваших API-ключей, вместо того чтобы создавать их по одному в консоли. Самый распространённый сценарий использования — пакетная выдача: каждому члену команды, клиенту или проекту предоставляется собственный ключ с отдельными ограничениями на расходы, доступные модели и срок действия. В сочетании с запланированной задачей можно также назначить каждому ключу дневной бюджет с автоматическим сбросом.Лимит квоты
remain_quota ограничивает общую сумму расходов по этому ключуЛимит моделей
models задаёт список разрешённых моделей; запросы к остальным отклоняютсяСрок действия
expired_time задаёт время истечения срока действия, после которого ключ перестаёт работатьКак получить персональный access token
Для аутентификации в Token Management API используется персональный access token (начинающийся сnap_), который отличается от API-ключа.
Откройте раздел Personal Access Tokens
api.apiyi.com/account/profile. В разделе Параметры аккаунта (Account Options) нажмите Personal Access Tokens → Create Token.Выберите необходимые разрешения Model keys
Задайте срок действия и список разрешенных IP-адресов

Эндпоинты
Все эндпоинты аутентифицируются одинаково: укажите personal access token в заголовкеAuthorization.
Префикс Bearer необязателен.
https://api.apiyi.com.
Создание token
Пример запроса
Поля запроса
Пример ответа
Получение открытого текста ключа
- Для персонального токена доступа требуется разрешение Model keys · Reveal secret, иначе вы получите 403
ACCESS_TOKEN_SCOPE_DENIED. - Возвращаемый
keyне содержит префиксаsk-. Добавьте его в начало самостоятельно. В приведенном выше примере фактический API-ключ —sk-K1RPzapu…. - Сразу же сохраните его и передавайте по защищенному каналу. Не оставляйте тело ответа в лог-файлах.
Пакетное создание
Серверного эндпоинта для пакетного создания нет — передача чего-то вродеcount в теле запроса
не даст эффекта и все равно создаст только один token. Пакетный выпуск выполняется циклом на клиенте.
- Python
- Node.js
- cURL
Использование трёх ограничений
Ограничение квоты
remain_quota ограничивает сумму, которую можно потратить с помощью token. Конвертация соответствует
API запроса баланса:
Правило конвертации
remain_quota значение
5000000, а для unlimited_quota — значение false. Текущий объём расходов можно посмотреть в поле
used_quota token.
remain_quota — это разовый общий лимит, который не пополняется автоматически. Чтобы установить дневной бюджет, см. раздел Сценарий: автоматический сброс дневных лимитов для каждого ключа ниже.
Ограничение моделей
models — это список разрешённых моделей, разделённых запятыми. После его установки вызовы моделей, не входящих в список, отклоняются:
models, ограничений не будет.
Ограничение срока действия
expired_time — это временная метка в формате Unix в секундах; значение -1 означает, что срок действия не ограничен. Например, ключ, срок действия которого истекает через 30 дней:
Получение списка tokens
Обновление token
Сценарий: ежедневные лимиты для каждого ключа с автоматическим сбросом
Когда компания передаёт ключи рабочим процессам, участникам команды или нижестоящим проектам, часто требуется, чтобы «каждый ключ мог расходовать не более $5 в день, а на следующий день лимит восстанавливался». Если рабочий процесс выйдет из-под контроля, ущерб будет ограничен бюджетом на один день. На платформе пока нет встроенного поля «дневная квота», но эндпоинт обновления, описанный выше, и запланированное задание, которое запускается раз в полночь, решают эту задачу: каждый день оно устанавливаетremain_quota для этих ключей на дневной лимит. Сами ключи никогда не меняются, поэтому участники команды продолжают использовать тот же ключ. Когда дневной бюджет ключа исчерпан, запросы отклоняются и не тарифицируются; после полуночного сброса они снова работают.
Создайте персональный токен доступа
Укажите ключи, для которых нужно установить лимит, и их дневные лимиты
id каждого ключа с помощью эндпоинта списка и внесите их в DAILY_BUDGET_USD в скрипте ниже.Запускайте скрипт раз в день в 00:00 (UTC+8)
Скрипт сброса
- Без повторных сбросов: если он запускается дважды за один день (например, при наверстывающем запуске планировщика или ручном повторном запуске), он не выдает бюджет ещё на один день
- Переносит перерасход на следующий день: квота — это мягкий лимит (см. ниже), поэтому сумма превышения за вчера вычитается сегодня, помогая со временем удерживать средний дневной расход в пределах лимита. Установите
CARRY_OVERDRAFTв значениеFalse, если не хотите этого - Выводит расходы за вчера: при каждом запуске скрипт записывает, сколько потратил каждый ключ за предыдущий период, поэтому журнал одновременно служит простым ежедневным отчетом
Планирование
Поместите token в файл окружения, доступный только вам, а затем запускайте скрипт ежедневно с помощью cron:TZ в скрипте.
Что нужно знать, прежде чем полагаться на это
- Сброс перезаписывает квоту, а не добавляет к ней средства: неиспользованный бюджет не переносится на следующий день. Любые изменения квоты этих ключей, внесённые вами вручную в консоли, также будут перезаписаны при следующем сбросе
- Запросы, выполняющиеся в полночь: запрос, отправленный до полуночи и завершившийся после неё, может быть тарифицирован за счёт квоты нового дня — обычно это небольшая сумма
- Если скрипт не запустится, ключи останутся исчерпанными: вызовы будут временно заблокированы, но дополнительные средства потрачены не будут. Настройте оповещения об ошибках для запланированной задачи
- Баланс аккаунта по-прежнему является главным ограничением: если сумма дневных лимитов ключей превышает баланс аккаунта, сначала закончатся средства на балансе и все ключи перестанут работать
- Нужно сегодня немного увеличить лимит одного ключа? Увеличьте квоту этого ключа с помощью эндпоинта обновления
remain_quota; на следующий день она, как обычно, сбросится до лимита
Отключение и удаление
Отключение (сохраняет запись)
После отключения ключ сразу перестает работать — запросы с ним возвращают 401 — но запись token и история его использования сохраняются.Удаление (необратимо)
FAQ
Почему ключ, возвращённый при создании, не работает?
Почему ключ, возвращённый при создании, не работает?
key (с последовательностью * посередине), поэтому его нельзя использовать напрямую.
Вызовите POST /api/token/{id}/key с возвращённым id, чтобы получить исходный текст (требуется разрешение «Показать секрет»),
затем добавьте в начало sk-. Если старый скрипт напрямую использует key из ответа на создание, добавьте этот шаг при переходе на персональный токен доступа.Почему у только что созданного токена отображается недостаточная квота?
Почему у только что созданного токена отображается недостаточная квота?
remain_quota, ни unlimited_quota со значением true.
В результате такой комбинации по умолчанию создаётся токен с нулевой квотой. Создайте его заново, явно указав один из двух параметров.Почему model_limits или allow_ips не действуют?
Почему model_limits или allow_ips не действуют?
model_limits_enabled, сейчас не действуют. Их передача
не вызывает ошибки, но значения не сохраняются. Используйте models, чтобы ограничить доступные модели; ограничения по исходному IP пока нужно настраивать самостоятельно.Можно ли создать несколько токенов одним запросом?
Можно ли создать несколько токенов одним запросом?
count не
даёт результата. Вместо этого выполняйте вызов создания в цикле на стороне клиента — см. раздел о пакетном создании выше.Сколько токенов может быть у одной учётной записи?
Сколько токенов может быть у одной учётной записи?
Можно ли ограничить ежедневные расходы по каждому ключу и сбрасывать лимит на следующий день?
Можно ли ограничить ежедневные расходы по каждому ключу и сбрасывать лимит на следующий день?
remain_quota на дневной лимит. Ключи не
меняются; когда бюджет ключа исчерпан, вызовы отклоняются и плата за них не взимается. На следующий день ключ снова работает.
Полный скрипт и важные замечания приведены выше в разделе Сценарий: ежедневные лимиты для отдельных ключей с автоматическим сбросом.После обновления остальные поля были очищены
После обновления остальные поля были очищены
GET полный объект, измените его, а затем
PUT целиком, а не отправляйте только изменённые поля.Чем отключение отличается от удаления?
Чем отключение отличается от удаления?
status: 2) сразу прекращает работу ключа, но сохраняет запись и историю использования;
в любой момент можно вернуть ключ в 1. Удаление необратимо и стирает запись. Для временной приостановки лучше отключить ключ.Как узнать, сколько потрачено по каждому ключу?
Как узнать, сколько потрачено по каждому ключу?
used_quota токена содержит суммарные расходы по этому ключу (÷ 500 000 = USD). Чтобы посмотреть разбивку
по периодам или сведения об отдельных вызовах, отфильтруйте записи по имени токена на странице журнала в консоли — см.
Как просмотреть записи о вызовах.Важные примечания
- При массовом создании добавляйте небольшую задержку между вызовами, чтобы избежать высокого мгновенного числа параллельных запросов
- Задавайте каждому ключу осмысленное значение
name(например,team-aliceилиprod-webhook), чтобы позже можно было атрибутировать использование поtoken_nameв логах - Для ротации: создайте новый ключ, переключите трафик, отключите старый ключ, понаблюдайте некоторое время и удаляйте его только после того, как убедитесь в отсутствии вызовов
Связанная документация
- Как просмотреть историю вызовов — детализация вызовов и списаний по каждому ключу в консоли
- API проверки баланса — остаток средств на счете
- Как создать API-ключ — создание вручную в консоли
- Tokens и группы — для чего нужны группы и как их выбирать