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

Чат с ИИ удобен для человека, но продукт так не построишь: автодополнение в редакторе, бот поддержки, фильтр отзывов — всё это программа, которая общается с моделью напрямую. Мост между вашим кодом и моделью называется API. Этот курс объясняет, как он устроен, без привязки к конкретному вендору: концепции везде одинаковые.

Что такое API и зачем он

API (интерфейс программирования приложений) — это способ, которым одна программа вызывает другую. В случае языковых моделей вы отправляете HTTP-запрос с текстом, а в ответ получаете сгенерированный текст — тот же диалог, что в чате, только машиночитаемый.

Что это даёт по сравнению с чатом:

Автоматизация. Тысяча однотипных задач выполняется скриптом, а не копированием вручную.
Встраивание. ИИ становится функцией вашего продукта: кнопка «сократить текст», умный поиск, классификатор тикетов.
Контроль. Системный промпт, параметры и формат ответа фиксированы в коде — пользователи не могут случайно «сломать» поведение.
Конвейеры. Ответ модели можно сразу прогнать через валидацию, парсинг и отправить дальше.

Ключевые понятия

Понятие	Простое объяснение
API-ключ	Пароль вашей программы к сервису. Утёк — платите за чужие запросы
Токен	Фрагмент текста (часть слова, слово или несколько коротких слов). Модель считает и оплачивает всё в токенах
Контекстное окно	Максимальный объём текста, который модель «держит в голове» за один запрос: ваши сообщения, её ответы, документы
Системный промпт	Инструкция, задающая роль и правила на весь диалог; пользователь её не видит
Температура	«Полёт фантазии» от 0 до ~2: ниже — предсказуемо и сухо, выше — разнообразно и рискованно
Стриминг	Получение ответа по мере генерации, слово за словом, а не одним куском в конце

Структура запроса

Тело запроса — это JSON с тремя главными частями: сообщения, модель и параметры. Сообщения образуют диалог: system задаёт поведение, user — реплики пользователя, assistant — предыдущие ответы модели.

Пример универсального запроса (URL абстрактный, у реальных провайдеров будет свой):

curl https://api.example-llm.ru/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_KEY" \
  -d '{
    "model": "model-name",
    "messages": [
      {
        "role": "system",
        "content": "Ты — ассистент службы поддержки интернет-магазина. Отвечай кратко и вежливо. Если данных о заказе нет — честно скажи об этом и предложи связаться с оператором."
      },
      {
        "role": "user",
        "content": "Где мой заказ №4512?"
      }
    ],
    "temperature": 0.3,
    "max_tokens": 300
  }'

Примерный вид ответа:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "К сожалению, у меня нет данных о статусе заказа №4512..."
      }
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 31
  }
}

Про параметры, если коротко:

Температура. Простыми словами: это ручка случайности. Для классификации, извлечения данных и кода ставьте ближе к 0 — нужен стабильный, повторяемый результат. Для мозгового штурма и креатива повышайте.
Максимальная длина ответа. Ограничение сверху: защита от «разговорчивой» модели, которая сгенерирует эссе там, где нужны два предложения.
Название модели. У провайдеров их обычно несколько: быстрые и дешёвые для массовых задач, мощные — для сложных.

Стриминг

Обычный запрос ждёт, пока модель сгенерирует весь ответ, и возвращает его целиком. При стриминге ответ приходит порциями по мере генерации — в чатах вы видите этот эффект как «печатающийся» текст.

Зачем это в продукте: время до первого слова падает с десятков секунд до долей секунды, и интерфейс ощущается живым, даже если полный ответ генерируется так же долго. Технически меняется формат ответа (последовательность мелких сообщений вместо одного JSON), а логика обработки чуть усложняется.

Из чего складывается стоимость

Почти все API тарифицируются за токены, отдельно за вход (ваш запрос) и выход (ответ модели); выход обычно дороже входа. Формула простая:

Стоимость = (токены запроса × цена входа) + (токены ответа × цена выхода)

Что это значит на практике:

Весь диалог — это запрос. Если вы отправляете историю из 20 сообщений, платите за неё целиком при каждом запросе. Длинные диалоги дорожают с каждым шагом.
Системный промпт тоже стоит денег. Тяжёлая инструкция на 2000 токенов умножается на каждый вызов.
Разумные ограничения — прямая экономия. max_tokens, краткие промпты, резюме вместо полных документов в длинных цепочках.
Считайте до запуска. Оцените токены типового запроса, умножьте на ожидаемое число вызовов в месяц — получите бюджет до, а не после счёта.

Ограничения и безопасность

Лимиты. API ограничивают число запросов в минуту и токены в минуту. Причины инженерные: общий пул мощностей делится между всеми клиентами. Встраивайте обработку ошибок 429: пауза и повтор запроса, а не падение приложения.

Безопасность ключей. Ключ — это деньги и репутация. Правила железные:

Ключ не попадает в код репозитория, даже частный. Сканирователи секретов находят их за минуты, а история git хранит вечно.
Храните ключ в переменных окружения или секрет-менеджере, а на проде — с ротацией и разными ключами для разных окружений.
Никогда не отправляйте ключ в браузер пользователя. Запросы к модели делает ваш бэкенд, фронтенд обращается только к нему.

Правовые и приватностные ограничения зависят от провайдера и юрисдикции: проверьте, можно ли отправлять в API персональные данные клиентов, и что происходит с данными после запроса.

Когда API оправдан

API нужен, если ИИ — часть продукта или автоматизации: регулярные задачи, интеграции, программная обработка ответов. Чата достаточно, если работаете в диалоговом режиме, задачи разовые, а результат всё равно читает человек. Начинать лучше с чата и готовых промптов — и переходить к API, когда объём или продукт этого потребует.

Ключевые выводы

API превращает диалог с моделью в вызов из кода: автоматизация, встраивание в продукт, контроль поведения через системный промпт.

Запрос — это JSON с сообщениями (system/user/assistant), моделью и параметрами; температура управляет предсказуемостью, лимит длины — экономией.

Платите за токены входа и выхода, причём вся история диалога считается входом при каждом запросе — длинные диалоги дорожают.

Ключи хранятся в переменных окружения и секрет-хранилищах, никогда в коде и репозитории; ошибки лимитов обрабатывайте повтором с паузой.

Для разовых задач человеку хватает чата; API — про масштаб и интеграции.

Что дальше

Курс «Агенты: что это, как работают и когда нужны» покажет следующий шаг: как из одиночных запросов собирается самостоятельно действующая система. А курс «MCP: зачем ИИ доступ к внешним инструментам» объяснит, как модели стандартизированно подключаются к внешним сервисам и данным.

Введение в API языковых моделей