Использование API-шлюза ИИ
Один API-ключ для вызова моделей разных провайдеров, оплата с баланса аккаунта по фактическому использованию:
- Создайте ключ в разделе «ИИ-сервисы → API-шлюз → API-ключи» и выберите ценовую группу для каждого провайдера; можно задать месячный лимит расходов и позже изменить его в списке ключей
- Поддерживаются три формата запросов — OpenAI, Anthropic и Gemini; для подключения обычно достаточно сменить адрес шлюза и ключ
- Цена = официальная цена × коэффициент ценовой группы; у некоторых групп есть цены в непиковое время
- Перед вызовом резервируется сумма, после завершения вызов оплачивается по фактическому использованию, а с баланса списывается одной суммой раз в минуту
- Раздел «Использование и журналы» содержит статистику и подробности каждого вызова
Для чего нужен шлюз
API-шлюз в составе ИИ-сервисов — единая точка вызова больших языковых моделей: одним API-ключом можно вызывать модели разных провайдеров, а оплата списывается с баланса аккаунта по фактическому использованию. Заводить аккаунт и пополнять баланс у каждого провайдера отдельно не нужно.
- Официальные SDK работают без изменений: обычно достаточно изменить base_url и api_key; структуры запросов и ответов остаются прежними.
- Поддерживаются три формата запросов — OpenAI, Anthropic и Gemini, причём форматы можно сочетать: например, вызывать модель Claude через SDK OpenAI — шлюз преобразует запрос автоматически.
- Цена определяется ценовой группой: у одной модели в одной группе только одна цена. Если в группе несколько маршрутов и один из них выдаёт ошибку, запрос автоматически переходит на следующий маршрут той же группы, а цена не меняется.
Создание ключа API
- Откройте страницу ключей API: В консоли откройте «ИИ-сервисы → API-шлюз → API-ключи» и нажмите «Создать ключ» справа вверху.
- Укажите название, ценовую группу и месячный лимит: Название лучше давать по назначению, например production, test, cursor. Для провайдеров, у которых доступно несколько групп, нужно для каждого выбрать значение в поле «Ценовая группа»; если не выбрать, используется группа по умолчанию этого провайдера. Пустой месячный лимит расходов означает отсутствие ограничения, а 0 запрещает расходы в этом месяце; позже лимит можно изменить в списке ключей кнопкой «Изменить лимит» — для этого нужно подтвердить личность.
- Подтвердите личность: После нажатия «Создать» нужно подтвердить личность: если включена двухфакторная аутентификация (2FA), введите 6-значный код из приложения-аутентификатора, если нет — код, отправленный на почту. После подтверждения в течение 10 минут в рамках этого входа можно создавать новые ключи и менять лимиты без повторной проверки.
- Сразу сохраните ключ в открытом виде: Ключ начинается с sk-nc-, за которым идёт строка, и показывается только один раз: сервер хранит только его хеш. Скопируйте ключ в менеджер паролей до закрытия диалога.
После закрытия диалога открытый ключ исчезает навсегда — платформа хранит хеш, а не сам ключ. Если не сохранили его, остаётся удалить ключ и создать новый. Удаление действует сразу и отключает всё, что ещё использует этот ключ.
Ценовые группы
Ценовая группа определяет, по какой цене тарифицируются вызовы моделей конкретного провайдера с этим ключом: цена = официальная цена × коэффициент группы. Группы разделены по провайдерам: у каждого свои группы и одна группа по умолчанию.
- При создании ключа группу нужно выбирать только для провайдеров, у которых две группы или больше; если группа одна, выбирать нечего. Для провайдеров без выбранной группы используется их группа по умолчанию.
- Столбец «Группа» в списке ключей показывает выбранную для каждого провайдера группу и её коэффициент; нажмите «Сменить», чтобы изменить группу, — новая цена действует со следующего вызова.
- Вызовы идут только через маршруты выбранной группы и не переключаются на другие группы, поэтому цена одной и той же модели не меняется из-за смены маршрута.
Если группа, выбранная для провайдера, отключена, в списке появится отметка «Группа отключена», и вызовы моделей этого провайдера с этим ключом будут отклоняться (HTTP 403). Нажмите «Сменить» и выберите другую группу.
Первый вызов
Адрес шлюза — это домен, на котором открыта консоль. На странице «Панель управления» есть примеры curl в трёх форматах — OpenAI, Anthropic и Gemini, ещё один пример есть в окне, которое появляется после создания ключа; адрес шлюза в них уже подставлен.
- OpenAI — /v1/chat/completions — Заголовок Authorization со значением Bearer и вашим ключом
- Anthropic — /v1/messages — Заголовок x-api-key
- Gemini — /v1beta/models/имя_модели:generateContent, для потоковой передачи — :streamGenerateContent — Заголовок x-goog-api-key или параметр адреса ?key=
- В официальном SDK укажите шлюз в base_url и этот ключ в api_key; остальной код остаётся прежним.
- Кроме того, доступны /v1/models (список доступных моделей), /v1/embeddings (текстовые векторы) и /v1/images/generations (генерация изображений, оплата за каждое изображение) — все они вызываются в формате OpenAI.
- В поле model запроса укажите идентификатор модели, показанный на её карточке в разделе «Каталог моделей». Если он указан неверно или модель не опубликована, возвращается 404.
Каталог моделей и отображение цен
«Каталог моделей» показывает все доступные модели по провайдерам с поиском по названию, slug, описанию или возможностям, а также контекстом, максимальным выводом и другими параметрами.
- Цена = официальная цена × коэффициент ценовой группы. Вкладка «Все» показывает цены по группе по умолчанию каждого провайдера; открыв конкретного провайдера, можно переключаться между его группами. Множитель в правом верхнем углу карточки — это коэффициент текущей группы.
- У моделей с оплатой за токены цена разделена на ввод и вывод в расчёте на 1 миллион токенов; если есть цена чтения из кэша, она указана отдельной строкой. У моделей изображений, аудио и видео, которые тарифицируются за изображение, секунду, минуту или вызов, на карточке сразу указана цена за единицу.
- На карточках некоторых моделей есть строка «Промпт больше» с определённой длиной и ценой: если промпт в запросе длиннее этого значения, весь запрос тарифицируется по цене из этой строки.
- Если на карточке модели есть строка «Веб-поиск», то при использовании встроенного веб-поиска модели каждый поиск оплачивается дополнительно.
Если для группы задана цена в непиковое время, на карточке отображаются отметка «Непиковое время» и коэффициент, а при наведении курсора видны часы пиковой нагрузки; вне пиковых часов к цене группы применяется этот коэффициент, время определяется по моменту отправки запроса. При отметке «В этой группе пока нет маршрутов» перечислены группы, через которые эта модель доступна; отметка «Недоступно» означает, что сейчас модель нельзя вызвать ни через одну группу.
Использование и журналы
В разделе «ИИ-сервисы → API-шлюз → Использование и журналы» вверху находится статистика, которую можно переключать между периодами 24 часа, 7, 30 и 90 дней (по умолчанию 7 дней), а внизу — подробности вызовов.
- Статистика: число запросов, списанная сумма, общее число токенов (включая кэш), доля успешных запросов, средняя задержка, а также динамика по дням и рейтинги по моделям и по ключам.
- Подробности: для каждого вызова — время, модель, потоковый ли режим, токены ввода / вывода / кэша, списанная сумма, коэффициент, задержка и статус; есть фильтр по slug модели.
- В подробностях записываются только вызовы, которые дошли до модели; статусы — «Успешно» и «Ошибка», записи со статусом «Ошибка» не оплачиваются. Запросы, отклонённые до передачи модели (например, из-за недействительного ключа, исчерпанного месячного лимита, недостаточного баланса или отключённой группы), в подробностях не появляются — причину смотрите в сообщении об ошибке, которое вернул API.
- Столбец «Коэффициент» показывает коэффициент группы без скидки за непиковое время; сколько фактически списано за каждый вызов, смотрите в столбце «Начислено USD».
Как рассчитывается оплата
Оплата списывается с баланса аккаунта по фактическому использованию, отдельно пополнять этот сервис не нужно. Стоимость каждого вызова = официальная цена × коэффициент группы; если у группы есть непиковое время, в это время дополнительно применяется непиковый коэффициент, время определяется по моменту отправки запроса.
- Перед вызовом резервируется сумма исходя из длины ввода и максимального вывода модели; после завершения вызов оплачивается по фактическому использованию, а излишек резерва освобождается. Если доступного баланса не хватает на резерв, возвращается ошибка о недостатке средств (HTTP 402), в сообщении указано, сколько нужно зарезервировать и сколько доступно сейчас.
- Стоимость вызовов накапливается и списывается с баланса одной суммой раз в минуту; в счетах раздела «Финансы» каждый час появляется запись «Использование ИИ-сервисов (сводка за 1 час)».
- Когда доступный баланс опускается до $5 или ниже, платформа один раз напомнит вам об этом через внутренние сообщения и другие каналы уведомлений; если баланс поднимется выше $5 и снова опустится, напоминание повторится. В это время ответы API содержат заголовки X-Tovanix-Balance-Low: 1 и X-Tovanix-Balance-Available (текущая доступная сумма) — по ним программа может заранее напомнить о пополнении.
- Для каждого ключа можно задать собственный месячный лимит расходов; он считается по календарному месяцу и автоматически обнуляется в следующем месяце. Перед каждым вызовом выполняется проверка: если расходы за месяц вместе с выполняющимися вызовами достигли лимита, новые вызовы не пропускаются. Последний вызов оплачивается по фактическому использованию, поэтому расходы за месяц могут немного превысить лимит.
Предостережения
- Ключ в открытом виде показывается только при создании — сохраните его сразу.
- Удаление ключа действует сразу и необратимо. Если нужно лишь временно остановить ключ, нажмите в списке «Отключить», а позже — «Включить».
- Месячный лимит 0 полностью блокирует расходы ключа в этом месяце; не используйте 0 как безлимит.
- Шлюз обрабатывает запросы на стандартном уровне: указанный в запросе уровень скорости (например, speed: fast у Claude или service_tier у OpenAI) игнорируется, а оплата идёт по стандартной цене.
- Если при вызове в формате Anthropic передаётся инструмент веб-поиска, а лимит числа поисков в запросе не указан, на один запрос выполняется не более 10 поисков.
Устранение проблем
- Возвращается 401: ключ недействителен или отключён — Ключ указан с ошибкой, удалён или отключён — На странице «API-ключи» убедитесь, что ключ в статусе «Включено»; если он отключён, нажмите «Включить». Удалённый ключ восстановить нельзя — можно только создать новый.
- Возвращается 402: достигнут месячный лимит расходов — Расходы по этому ключу в этом месяце достигли лимита (лимит 0 означает, что расходы в этом месяце запрещены) — В следующем месяце ключ снова заработает автоматически. Если ждать нельзя, на странице «API-ключи» нажмите у этого ключа «Изменить лимит» и увеличьте лимит или оставьте поле пустым, чтобы снять ограничение (нужно подтвердить личность); новый лимит действует со следующего вызова.
- Возвращается 402: недостаточно средств — Доступного баланса не хватает на резерв для этого запроса — В сообщении об ошибке указано, сколько нужно зарезервировать для этого запроса и сколько доступно сейчас; пополните баланс и повторите попытку.
- Возвращается 403 или 503: группа отключена или нет доступных маршрутов — Группа, выбранная в ключе для этого провайдера, отключена, либо в группе временно нет доступных маршрутов для этой модели — На странице «API-ключи» нажмите «Сменить» и выберите другую группу; на карточке модели в разделе «Каталог моделей» перечислены группы, через которые она доступна. Можно также повторить попытку позже.
- Счёт отличается от цены в каталоге моделей — Вкладка «Все» показывает цену группы по умолчанию, а в ключе выбрана другая группа; либо запрос пришёлся на непиковое время, промпт превысил порог длинного контекста или использовался веб-поиск — Ориентируйтесь на списанную сумму в каждой записи раздела «Использование и журналы».
- Рабочее приложение внезапно отключается — Ключ удалён или отключён — Отключённый ключ можно вернуть кнопкой «Включить» в списке; вместо удалённого остаётся только создать новый ключ и заменить им старый в приложении.
Часто задаваемые вопросы
Сколько кода нужно изменить для подключения?
Обычно меняются две вещи: base_url указывает на шлюз, а api_key заменяется ключом платформы. Шлюз совместим с официальными SDK и протоколами: тело запроса, структура ответа и формат потоковой передачи остаются прежними.
Почему сумма в счёте отличается от цены в каталоге моделей?
Вкладка «Все» показывает цены по группе по умолчанию каждого провайдера; если в вашем ключе выбрана другая группа, оплата идёт по её цене. Кроме того, стоимость отдельного вызова может отличаться от показанной цены из-за скидки в непиковое время, перехода всего запроса на другую цену, когда промпт длиннее порога длинного контекста, и отдельной оплаты каждого веб-поиска. Ориентируйтесь на списанную сумму в каждой записи раздела «Использование и журналы».
Как ограничить расходы отдельного проекта?
Создайте для этого проекта отдельный ключ и задайте месячный лимит расходов. Лимит считается по ключу, поэтому проекты не влияют друг на друга; чтобы поменять лимит позже, нажмите «Изменить лимит» в списке ключей (нужно подтвердить личность).
Связанные страницы: Центр помощи · Руководства и вопросы · ИИ-сервисы · Документация API
Загрузка…