PRO.02
API и работа с моделями
РЕЗУЛЬТАТ УРОКА
Подключать модели через API безопасно и управляемо.Главное за 30 секунд
API превращает модель в часть продукта: поэтому важны ключи, лимиты, трассировка, обработка ошибок и контроль стоимости.
Разбираемся
Работа с моделью через интерфейс чата и работа через API — принципиально разные вещи. В чате вы общаетесь; через API вы строите систему. Это означает: управление ключами, обработка ошибок, контроль стоимости, логирование, тестирование. Всё то, что делает разницу между демо и production-приложением.
Путь одного вызова
Ветки, без которых прод ломается
Главное: верхний ряд рисуют все туториалы; нижний определяет, доживёт ли система до второго дня работы.
Верхний ряд — то, что все рисуют в туториалах. Нижний — то, из-за чего система падает в первый рабочий день.
API key и безопасность
API-ключ — это не пароль для чата, это учётные данные для программного доступа. Ключ должен жить только на сервере: в переменных окружения или в системе управления секретами. Если ключ попал в код, который загружается в браузер, — он публичный, независимо от того, как это выглядит в редакторе. Любой посетитель может открыть инструменты разработчика и прочитать его. Отдельные ключи для разработки, тестирования и работы: скомпрометированный тестовый ключ не должен давать доступ к рабочему счёту.
Где может жить ключ
| Критерий | На сервере — верно | В браузере — утечка |
|---|---|---|
| Как выглядит | Браузер обращается к вашему серверу, сервер — к модели | Браузер обращается к модели напрямую |
| Кто видит ключ | Только ваш сервер | Любой посетитель через инструменты разработчика |
| Что можно сделать с ключом | — | Тратить ваш бюджет без ограничений |
| Как узнают об утечке | — | По счёту в конце месяца |
| Признак в проекте | Ключ читается в серверной части | В имени переменной есть пометка «публичная» |
Предсказуемый формат ответа
Модель по умолчанию отвечает свободным текстом, и это плохая основа для автоматизации: сегодня «Оплата», завтра «billing», послезавтра «вопрос по оплате». Современные API умеют принимать схему ответа — перечень полей и допустимых значений — и гарантировать, что ответ ей соответствует. Ключевая деталь: для полей с ограниченным набором значений этот набор нужно перечислить явно. Иначе однажды придёт значение не из списка, и обработка молча пойдёт по ветке «всё остальное».
Три типа ошибок API и реакция на каждый
| Критерий | Как правильно | Цена ошибки |
|---|---|---|
| Лимит запросов исчерпан | Подождать и повторить, увеличивая паузу. Не более трёх попыток | Мгновенный повтор порождает новый отказ — счёт растёт, задача не двигается |
| Сервис недоступен | Повторить несколько раз, затем сообщить об ошибке и уведомить дежурного | Бесконечные повторы при затяжной недоступности ложатся на ваш сервер |
| Ошибка в самом запросе | Записать в журнал и не повторять: повтор даст тот же результат | Три одинаковых отказа вместо одного и утроенная задержка |
| Слишком долгий ответ | Оборвать по таймауту в 30–60 секунд и показать понятное сообщение | Пользователь смотрит на зависший экран, не понимая, работает ли что-то |
| Любая из ошибок | Считать вызовы и сумму, ограничивать расход за сутки | Ошибка в логике за ночь превращается в счёт на тысячи |
Токены и стоимость
Модели считают расход в токенах — условных кусочках текста. Для английского примерно 750 слов на 1000 токенов, для русского ближе к 500 словам: за один и тот же текст по-русски вы заплатите заметно больше. Отправленное и полученное тарифицируются отдельно, и полученное обычно в три-четыре раза дороже. Порядок величин считается до запуска: 1000 обращений в день по 2000 отправленных и 500 полученных токенов — это 60 и 15 миллионов токенов в месяц. Подставьте тариф своего провайдера и получите сумму заранее, а не по факту.
Минимум перед первым запуском
Ни один пункт не про качество ответов — всё про то, чтобы система не легла и не разорила.
- Ключ вне клиентской частиТолько на сервере, только из переменных окружения. Отдельные ключи для разработки и работы.
- Ограничение длины ответаБез потолка модель может выдать несколько тысяч токенов на простой вопрос. Один такой ответ стоит копейки, десять тысяч — уже нет.
- Таймаут30–60 секунд, дальше — ошибка и понятное сообщение. Пользователь не должен смотреть на зависший экран.
- Повторы с ограничениемНе более трёх попыток, с растущей паузой, и только на временные ошибки. Не на ошибки в самом запросе.
- Журнал каждого обращенияМодель, объём отправленного и полученного, задержка, статус. Без этого нельзя ответить ни на «почему счёт вырос», ни на «почему стало медленно».
- Лимит на пользователя и на суткиПростой счётчик. Защищает и от ошибки в собственной логике, и от того, кто решит воспользоваться вашим бюджетом.
Что спросить перед запуском
5 пунктовПять вопросов, которые отделяют работающую систему от демонстрации.
- Если в ответе есть слово «браузер» или «клиент» — ключ публичный, и это нужно исправлять до запуска.
- Ответ «такого не бывает» означает, что ветка не написана. Нужно описание поведения для каждого типа отказа.
- Расход растёт вместе с использованием. Цифра, посчитанная на текущем объёме, ничего не говорит о том, что будет при успехе.
- Единственная защита от ошибки в цикле. Без него неудачная правка обнаруживается по счёту.
- Без журнала вопросы «почему дорого» и «почему медленно» остаются без ответа.
ПРИМЕР
Счёт на 40 тысяч за одну ночь
Ситуация. Скрипт обогащает карточки товаров описаниями через API. В цикле есть retry на любую ошибку без ограничения попыток и без паузы. Провайдер начинает отдавать 429 — лимит на аккаунт. Скрипт запущен на ночь без лимита расходов и без алертов.
Результат. К утру в логах 180 тысяч запросов вместо ожидаемых 4 тысяч: каждый 429 порождал мгновенный повтор, каждый повтор — новый 429. Часть попыток проходила и тарифицировалась. Три строки — предел попыток, экспоненциальная пауза, суточный лимит — стоили бы пятнадцати минут работы.
ПРАКТИКА
Сделайте сейчас
Спроектируйте один реальный сценарий обращения к модели, не написав ни строчки кода: где живёт ключ, какие поля вы ждёте в ответе и какие значения допустимы для каждого, что происходит при каждом из трёх типов ошибок, какой таймаут, и во что это обойдётся при 1000 обращений в день по тарифу вашего провайдера. Если последняя цифра вас удивила — это и есть главный результат упражнения.
ОГРАНИЧЕНИЯ
Где нужен человек
- Нельзя вшивать API-ключи в клиентское приложение или публиковать их в репозитории.
- Не запускайте неограниченные API-вызовы без мониторинга стоимости — счёт может вырасти за часы.
Смежные уроки
Материал проверен: 20 августа 2026. Инструменты и тарифы меняются — сверяйтесь с первоисточником.