Перейти к основному содержанию

Обзор API

API управления токенами позволяет программно управлять полным жизненным циклом ваших API-ключей, вместо того чтобы создавать их по одному в консоли. Самый распространённый сценарий использования — пакетная выдача: каждому члену команды, клиенту или проекту предоставляется собственный ключ с отдельными ограничениями на расходы, доступные модели и срок действия. В сочетании с запланированной задачей можно также назначить каждому ключу дневной бюджет с автоматическим сбросом.

Лимит квоты

remain_quota ограничивает общую сумму расходов по этому ключу

Лимит моделей

models задаёт список разрешённых моделей; запросы к остальным отклоняются

Срок действия

expired_time задаёт время истечения срока действия, после которого ключ перестаёт работать
Если вам нужен всего один или два ключа, быстрее создать их в консоли — см. Как создать API-ключ. Этот API предназначен для автоматизированной выдачи ключей, плановой ротации или интеграции управления ключами в ваши системы.

Как получить персональный access token

Для аутентификации в Token Management API используется персональный access token (начинающийся с nap_), который отличается от API-ключа.
1

Откройте раздел Personal Access Tokens

Перейдите на страницу своего профиля по адресу api.apiyi.com/account/profile. В разделе Параметры аккаунта (Account Options) нажмите Personal Access Tokens → Create Token.
2

Выберите необходимые разрешения Model keys

Эти три разрешения независимы друг от друга. Выбирайте только те, которые вам нужны:Скрипту для массового выпуска ключей понадобятся все три разрешения. Скрипту для мониторинга использования достаточно только Read.
3

Задайте срок действия и список разрешенных IP-адресов

Срок действия по умолчанию составляет 30 дней, поэтому мы рекомендуем выбрать более длительный период. Если ваш скрипт выпуска ключей работает на сервере со статическим IP, настоятельно рекомендуем настроить список разрешенных IP-адресов (IP allowlist). Этот список нельзя отредактировать после создания, поэтому сначала отладьте работу скрипта без него, а затем создайте отдельный рабочий token со списком разрешенных IP-адресов.
Создание персонального access token: имя, срок действия, список разрешенных IP-адресов и разрешения
Token с разрешениями Write и Reveal secret может создавать API-ключи, вызывающие модели. Относитесь к нему как к паролю от своего аккаунта.Персональный access token сам по себе не может вызывать модели, но может выпускать ключи, обладающие этой возможностью. Обязательно задайте для такого token список разрешенных IP-адресов, храните его в менеджере секретов, а не в коде, ни в коем случае не фиксируйте в репозитории и обновляйте до истечения срока действия.
Устаревшие системные tokens планируется вывести из эксплуатации 2026-11-11 (UTC+8). AccessTokens, созданные в разделе «Account Options - System Token», продолжат работать до этой даты. После нее они будут возвращать 401 ACCESS_TOKEN_LEGACY_RETIRED. Мы проанализируем интенсивность использования и при необходимости перенесем дату, но рекомендуем перейти на персональный access token уже сейчас. При переходе также проверьте ваши скрипты: эндпоинт создания теперь возвращает маскированный key. Чтобы получить открытый текст, вызовите POST /api/token/{id}/key, как описано ниже. См. Что такое персональный access token?

Эндпоинты

Все эндпоинты аутентифицируются одинаково: укажите personal access token в заголовке Authorization. Префикс Bearer необязателен. Базовый URL: https://api.apiyi.com.

Создание token

Пример запроса

Поля запроса

unlimited_quota по умолчанию равен false, а remain_quota по умолчанию равен 0 — если опустить оба параметра, будет создан token с нулевой квотой, который нельзя использовать. Либо явно укажите remain_quota, либо установите unlimited_quota в true.
Используйте поле models для белого списка моделей.Структура ответа также содержит model_limits, model_limits_enabled и allow_ips. Их передача не вызывает ошибки — эндпоинт по-прежнему возвращает 200, — но они в настоящее время не действуют, и при повторном чтении token они отображаются как неустановленные. Используйте models для ограничения доступных моделей. Ограничения по исходному IP-адресу на данный момент необходимо реализовывать на вашей стороне.

Пример ответа

key в ответе замаскирован и не может использоваться напрямую. Чтобы получить открытый текст, вызовите эндпоинт получения открытого текста с id из ответа.

Получение открытого текста ключа

  • Для персонального токена доступа требуется разрешение Model keys · Reveal secret, иначе вы получите 403 ACCESS_TOKEN_SCOPE_DENIED.
  • Возвращаемый key не содержит префикса sk-. Добавьте его в начало самостоятельно. В приведенном выше примере фактический API-ключ — sk-K1RPzapu….
  • Сразу же сохраните его и передавайте по защищенному каналу. Не оставляйте тело ответа в лог-файлах.

Пакетное создание

Серверного эндпоинта для пакетного создания нет — передача чего-то вроде count в теле запроса не даст эффекта и все равно создаст только один token. Пакетный выпуск выполняется циклом на клиенте.
Один пользователь может иметь не более 1 000 tokens. Это общее ограничение на весь аккаунт, и оно учитывает tokens, которые отключены, но не удалены. Как только вы его достигнете, эндпоинт создания начнет возвращать ошибку — удаляйте tokens, которые больше не используются, чтобы освободить слоты.Перед пакетным запуском выполните пагинацию по GET /api/token/?p=0&page_size=100, чтобы подсчитать уже имеющиеся. При ротации ключей обязательно выполняйте последний шаг: «создать новый ключ → перенаправить трафик → отключить старый ключ → удалить, когда не останется вызовов». Отключение без удаления оставляет слот занятым, поэтому через несколько циклов ротации вы упретесь в лимит.

Использование трёх ограничений

Ограничение квоты

remain_quota ограничивает сумму, которую можно потратить с помощью token. Конвертация соответствует API запроса баланса:

Правило конвертации

500,000 quota = $1.00 USD
Например, чтобы выдать клиенту ключ с лимитом $10, задайте для remain_quota значение 5000000, а для unlimited_quota — значение false. Текущий объём расходов можно посмотреть в поле used_quota token. remain_quota — это разовый общий лимит, который не пополняется автоматически. Чтобы установить дневной бюджет, см. раздел Сценарий: автоматический сброс дневных лимитов для каждого ключа ниже.

Ограничение моделей

models — это список разрешённых моделей, разделённых запятыми. После его установки вызовы моделей, не входящих в список, отклоняются:
В ответ возвращается HTTP 403, и плата не взимается. Если не указывать models, ограничений не будет.

Ограничение срока действия

expired_time — это временная метка в формате Unix в секундах; значение -1 означает, что срок действия не ограничен. Например, ключ, срок действия которого истекает через 30 дней:

Получение списка tokens

Основные поля:

Обновление token

Эндпоинт обновления требует полный объект — это не патч.Правильная последовательность: GET полный объект token, измените поля, которые хотите поменять, затем PUT весь объект обратно. Отправка только измененных полей очистит остальные.

Сценарий: ежедневные лимиты для каждого ключа с автоматическим сбросом

Когда компания передаёт ключи рабочим процессам, участникам команды или нижестоящим проектам, часто требуется, чтобы «каждый ключ мог расходовать не более $5 в день, а на следующий день лимит восстанавливался». Если рабочий процесс выйдет из-под контроля, ущерб будет ограничен бюджетом на один день. На платформе пока нет встроенного поля «дневная квота», но эндпоинт обновления, описанный выше, и запланированное задание, которое запускается раз в полночь, решают эту задачу: каждый день оно устанавливает remain_quota для этих ключей на дневной лимит. Сами ключи никогда не меняются, поэтому участники команды продолжают использовать тот же ключ. Когда дневной бюджет ключа исчерпан, запросы отклоняются и не тарифицируются; после полуночного сброса они снова работают.
1

Создайте персональный токен доступа

Предоставьте разрешения Ключи моделей · Чтение и Ключи моделей · Запись; разрешение «Показать секрет» не требуется. Если скрипт запускается на сервере с постоянным IP-адресом, настройте список разрешённых IP-адресов для токена.
2

Укажите ключи, для которых нужно установить лимит, и их дневные лимиты

Получите id каждого ключа с помощью эндпоинта списка и внесите их в DAILY_BUDGET_USD в скрипте ниже.
3

Запускайте скрипт раз в день в 00:00 (UTC+8)

Подойдёт cron, таймер облачной функции или любой другой планировщик — подробности ниже.

Скрипт сброса

Скрипт делает ещё три вещи:
  • Без повторных сбросов: если он запускается дважды за один день (например, при наверстывающем запуске планировщика или ручном повторном запуске), он не выдает бюджет ещё на один день
  • Переносит перерасход на следующий день: квота — это мягкий лимит (см. ниже), поэтому сумма превышения за вчера вычитается сегодня, помогая со временем удерживать средний дневной расход в пределах лимита. Установите CARRY_OVERDRAFT в значение False, если не хотите этого
  • Выводит расходы за вчера: при каждом запуске скрипт записывает, сколько потратил каждый ключ за предыдущий период, поэтому журнал одновременно служит простым ежедневным отчетом

Планирование

Поместите token в файл окружения, доступный только вам, а затем запускайте скрипт ежедневно с помощью cron:
Чтобы определить «день» в другом часовом поясе, измените время запуска cron и TZ в скрипте.

Что нужно знать, прежде чем полагаться на это

Квота — это мягкое ограничение, а не точный стоп-сигнал. Проверка квоты выполняется при запуске запроса, поэтому несколько параллельных запросов могут пройти проверку одновременно, а один дорогостоящий запрос (видео, изображения 4K, очень длинный контекст) может за один раз превысить лимит и увести баланс в минус. Чем выше количество параллельных запросов и цена единицы, тем больше будет превышение. Скрипт вычитает перерасход из квоты на следующий день; если какие-то ключи ни в коем случае не должны превышать лимит, ограничьте количество параллельных запросов на своей стороне или используйте models список разрешённых моделей, чтобы исключить дорогостоящие модели.
  • Сброс перезаписывает квоту, а не добавляет к ней средства: неиспользованный бюджет не переносится на следующий день. Любые изменения квоты этих ключей, внесённые вами вручную в консоли, также будут перезаписаны при следующем сбросе
  • Запросы, выполняющиеся в полночь: запрос, отправленный до полуночи и завершившийся после неё, может быть тарифицирован за счёт квоты нового дня — обычно это небольшая сумма
  • Если скрипт не запустится, ключи останутся исчерпанными: вызовы будут временно заблокированы, но дополнительные средства потрачены не будут. Настройте оповещения об ошибках для запланированной задачи
  • Баланс аккаунта по-прежнему является главным ограничением: если сумма дневных лимитов ключей превышает баланс аккаунта, сначала закончатся средства на балансе и все ключи перестанут работать
  • Нужно сегодня немного увеличить лимит одного ключа? Увеличьте квоту этого ключа с помощью эндпоинта обновления remain_quota; на следующий день она, как обычно, сбросится до лимита

Отключение и удаление

Отключение (сохраняет запись)

После отключения ключ сразу перестает работать — запросы с ним возвращают 401 — но запись token и история его использования сохраняются.

Удаление (необратимо)

Пакетное удаление также выполняется в виде цикла на стороне клиента:
Удаление нельзя отменить. Если вы хотите лишь временно приостановить key, вместо этого отключите его — история использования останется доступной для сверки.

FAQ

Эндпоинт создания возвращает замаскированный key (с последовательностью * посередине), поэтому его нельзя использовать напрямую. Вызовите POST /api/token/{id}/key с возвращённым id, чтобы получить исходный текст (требуется разрешение «Показать секрет»), затем добавьте в начало sk-. Если старый скрипт напрямую использует key из ответа на создание, добавьте этот шаг при переходе на персональный токен доступа.
Скорее всего, при создании не было задано ни remain_quota, ни unlimited_quota со значением true. В результате такой комбинации по умолчанию создаётся токен с нулевой квотой. Создайте его заново, явно указав один из двух параметров.
Эти поля, а также model_limits_enabled, сейчас не действуют. Их передача не вызывает ошибки, но значения не сохраняются. Используйте models, чтобы ограничить доступные модели; ограничения по исходному IP пока нужно настраивать самостоятельно.
Серверного эндпоинта для пакетного создания нет, а передача в теле запроса чего-то вроде count не даёт результата. Вместо этого выполняйте вызов создания в цикле на стороне клиента — см. раздел о пакетном создании выше.
Не более 1 000 на пользователя; отключённые, но не удалённые токены также учитываются. Когда достигнут лимит, создание новых токенов завершается ошибкой, пока вы не удалите ненужные. При смене ключей не забудьте выполнить удаление: одного отключения недостаточно, слот останется занятым.
Встроенного поля для ежедневной квоты нет, но это можно делать с помощью запланированной задачи: каждый день в 00:00 (UTC+8) вызывайте эндпоинт обновления, чтобы снова установить для этих ключей remain_quota на дневной лимит. Ключи не меняются; когда бюджет ключа исчерпан, вызовы отклоняются и плата за них не взимается. На следующий день ключ снова работает. Полный скрипт и важные замечания приведены выше в разделе Сценарий: ежедневные лимиты для отдельных ключей с автоматическим сбросом.
Для эндпоинта обновления требуется полный объект. Сначала GET полный объект, измените его, а затем PUT целиком, а не отправляйте только изменённые поля.
Отключение (status: 2) сразу прекращает работу ключа, но сохраняет запись и историю использования; в любой момент можно вернуть ключ в 1. Удаление необратимо и стирает запись. Для временной приостановки лучше отключить ключ.
Поле used_quota токена содержит суммарные расходы по этому ключу (÷ 500 000 = USD). Чтобы посмотреть разбивку по периодам или сведения об отдельных вызовах, отфильтруйте записи по имени токена на странице журнала в консоли — см. Как просмотреть записи о вызовах.

Важные примечания

Personal access token — это не API-ключ, и они не взаимозаменяемы
  • API-ключ (начинающийся с sk-) предназначен для эндпоинтов инференса /v1/*
  • Personal access token (начинающийся с nap_) предназначен для эндпоинтов управления /api/* и не может вызывать модели
Справка по ошибкам: 401 ACCESS_TOKEN_LEGACY_RETIRED означает, что вы все еще используете устаревший системный token, выведенный из эксплуатации. 401 This access token may not be used from the current IP address. означает, что запрос поступил с IP-адреса вне списка разрешенных адресов для данного token. 403 ACCESS_TOKEN_SCOPE_DENIED означает, что у token нет разрешения, необходимого для этого эндпоинта (см. таблицу «Эндпоинты»).
Обращайтесь с ключами в открытом виде с осторожностьюЭндпоинт retrieve-plaintext возвращает ключ, с помощью которого можно напрямую вызывать модели. Поэтому:
  • Не записывайте тела ответов, содержащие key, в лог-файлы и не фиксируйте их в репозитории
  • Передавайте ключи участникам команды по защищенным каналам, а не через групповые чаты
  • Этот открытый текст не содержит префикса sk-, поэтому распространенные сканеры секретов могут его не обнаружить — не полагайтесь на автоматические проверки в его поиске
Рекомендации по эксплуатации
  • При массовом создании добавляйте небольшую задержку между вызовами, чтобы избежать высокого мгновенного числа параллельных запросов
  • Задавайте каждому ключу осмысленное значение name (например, team-alice или prod-webhook), чтобы позже можно было атрибутировать использование по token_name в логах
  • Для ротации: создайте новый ключ, переключите трафик, отключите старый ключ, понаблюдайте некоторое время и удаляйте его только после того, как убедитесь в отсутствии вызовов

Связанная документация