Русский · English
Готовые примеры работы с API ИИ-чата на шести языках: Python, TypeScript (Node.js), Go, Java, C#, PHP. Подключить нейросеть в приложение одним HTTP-запросом: суммаризация текста, генерация текста, чат-бот с памятью диалога. Один LLM API, единый ключ, учёт токенов в ответе.
Каждый пример запускается сразу — без регистрации, без ключа, без карты. В коде зашит публичный демо-ключ.
git clone https://github.com/atlorium-api/ai-chat-api-client
cd ai-chat-api-client/python && pip install -r requirements.txt && python main.pyДемо-ключ: ответ модели — заглушка (мок). Реальная ИИ-модель не вызывается, токены не тратятся.
Доступные модели (GET /api/AiChat/models):
[ ] local Приватная — вход до 6000 токенов, недоступна
[*] basic Базовая — вход до 8192 токенов, доступна
[*] advanced Продвинутая — вход до 8192 токенов, доступна
[*] best Лучшая — вход до 8192 токенов, доступна
Выбрана: basic (Базовая) — первая доступная в списке.
Лимит входа: 8192 токенов
Дневная квота тарифа покрывает запросы к этой модели
Проверка длины до отправки:
Символов в запросе: 766
Оценка токенов: ~192 (приблизительно: символы / 4)
Влезает — отправляем.
── Выжимка ───────────────────────────────────────────────────────
Это ответ песочницы (mock): реальная ИИ-модель не вызывалась и токены не тратились. Ваше сообщение получено: «Сделай краткую выжимку текста ниже: 2–3 предложения, только суть, без вступлений и повторов.
Текст:
Клиент пишет, что п…». Активируйте аккаунт и используйте боевой ключ, чтобы получать реальные ответы модели.
──────────────────────────────────────────────────────────────────
Модель: basic
Токены: prompt 59 + completion 58 = 117
Сессия: dd8e248a7db5772ac46e7bca824e38cc
GET /api/AiChat/session/{id} → 404: в песочнице история сессии не сохраняется.
С боевым ключом сессия живёт час и доступна по этому же запросу — а sessionId
можно передать в следующий /send и продолжить диалог.
Напоминание: reply выше — заглушка песочницы, а не работа модели. Боевой ключ
вернёт настоящую выжимку тем же кодом.
Что именно показывает демо-ключ — и чего не показывает. У песочницы здесь две честные границы, и обе видно прямо в выводе выше.
reply— это заглушка, а не работа модели. Мок так и пишет: «реальная ИИ-модель не вызывалась и токены не тратились». Самой суммаризации в песочнице увидеть нельзя — видно только механику: выбор модели, проверку длины, учёт токенов, сессию. Боевой ключ вернёт настоящую выжимку тем же кодом, без единой правки.- В песочнице не сохраняются сессии.
GET /api/AiChat/session/{id}отдаёт404сразу после того, как/sendвернул этот самыйsessionId— проверено. Пример это переживает штатно и объясняет, а не падает. С боевым ключом сессия живёт час и работает.Всё остальное — реально: маршруты, коды ошибок, лимиты, формат ответа. Интеграцию можно написать и закрыть тестами до оплаты.
Суммаризация тикетов и переписки, извлечение смысла из отзывов, автоответы поддержки, генерация описаний товаров, классификация обращений, чат-бот с памятью диалога. Всё это — один POST-запрос: без своего GPU, без стойки с моделями и без отдельного договора на доступ к моделям.
Примеры не просто печатают JSON, а применяют API: в каждом есть функция summarize(), которая делает две вещи, которых нет в наивном примере.
1. Не хардкодит модель. Сначала GET /api/AiChat/models, потом — первая модель с isAvailable: true. Состав доступных моделей задаётся конфигурацией сервера и меняется; пример, зашивший конкретный id, однажды тихо сломается. Если доступных моделей нет вообще — пример честно об этом говорит и выходит, а не шлёт запрос в пустоту.
2. Считает длину ДО отправки. POST /send — платный вызов. Текст, который заведомо не влезет в лимит модели, сервер отклонит кодом 400 — денег за это не возьмёт (проверка идёт до удержания), но запрос всё равно бесполезен, а пользователю лучше сказать «слишком длинно» сразу, без сетевого круга. Поэтому пример грубо оценивает число токенов (эвристика «символы / 4» — приблизительная, и в коде это написано прямо) и сравнивает с maxInputTokens выбранной модели — это и есть единственный лимит длины сообщения, и он у каждой модели свой. Не влезает — говорим «сократите или разбейте на части» и не отправляем запрос.
Заодно пример читает цену выбранной модели. В /models каждая модель объявляет inputPricePer1kTokens, outputPricePer1kTokens и freeQuotaEligible — по ним видно, тарифицируются ли её токены, ещё до отправки запроса.
Посмотреть список моделей вообще без клонирования (этот вызов бесплатный):
curl -H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
"https://atlorium.com/api/AiChat/models"Отправить сообщение (а вот это уже платный вызов — см. «Цены и лимиты»):
curl -X POST "https://atlorium.com/api/AiChat/send" \
-H "Authorization: Bearer ak_sandbox_demo_mockdata_v1" \
-H "Content-Type: application/json; charset=utf-8" \
-d '{"message":"Что такое DNS?","sessionId":null,"model":"basic"}'| Язык | Запуск | Требуется |
|---|---|---|
| Python | pip install -r requirements.txt && python main.py |
Python 3.10+ |
| TypeScript / Node.js | npm install && npm start |
Node.js 20+ |
| Go | go run . |
Go 1.22+ |
| Java | java Main.java |
JDK 11+ (без зависимостей) |
| C# | dotnet run |
.NET 8+ |
| PHP | php main.php |
PHP 8.1+ |
Передать свой текст аргументом: python main.py "текст, который нужно сжать"
Ключ передаётся в заголовке Authorization:
Authorization: Bearer ВАШ_КЛЮЧ
| Ключ | Что делает |
|---|---|
ak_sandbox_demo_mockdata_v1 |
Демо-ключ. Публичный, один на всех. Регистрации не требует, денег не списывает, реальную модель не вызывает — reply возвращается заглушкой. Ответы детерминированы: один и тот же запрос всегда даёт тот же sessionId и тот же расход токенов, поэтому на них можно писать стабильные тесты. |
| Боевой ключ | Настоящие ответы модели. Получить в личном кабинете: atlorium.com |
Переход на боевой ключ не требует правок в коде — все примеры читают переменную окружения:
export ATLORIUM_API_KEY="ak_ваш_боевой_ключ"Ответ песочницы на /send помечен заголовком X-Atlorium-Sandbox: true — перепутать заглушку с ответом модели невозможно.
Базовый адрес: https://atlorium.com
| Метод | Путь | Назначение | Тарифицируется |
|---|---|---|---|
GET |
/api/AiChat/models |
Список моделей сервера с лимитами и доступностью | Нет |
POST |
/api/AiChat/send |
Отправить сообщение, получить ответ модели | Да |
GET |
/api/AiChat/session/{sessionId} |
Сведения о сессии: сколько сообщений, когда активна | Нет |
DELETE |
/api/AiChat/session/{sessionId} |
Удалить сессию и всю историю | Нет |
Ключ нужен всем четырём (без него 401), но квоту расходует только /send — именно он ходит в модель. Проверено живыми запросами: ответы /models и эндпоинтов сессии не помечены даже заголовком X-Atlorium-Sandbox.
Регистр в пути не важен: /api/aichat/send работает так же.
Тело запроса — JSON. Кодировка UTF-8 (Content-Type: application/json; charset=utf-8).
| Поле | Тип | Описание |
|---|---|---|
message |
string | Обязательное. Текст сообщения. Длина ограничена в токенах и зависит от модели — сверяйте с maxInputTokens из /models. Длиннее — 400. |
sessionId |
string / null | Идентификатор существующей сессии, чтобы продолжить диалог. null — создать новую. |
model |
string / null | id модели из /models. null — модель по умолчанию. |
Ответ может идти минутами — ставьте таймаут HTTP-клиента не меньше 10 минут. Обрыв соединения с вашей стороны запрос не отменяет, и он оплачивается. Подробно — в разделе «Время ответа и таймауты».
| Параметр | Где | Тип | Описание |
|---|---|---|---|
sessionId |
путь | string | 32 шестнадцатеричных символа — то, что вернул /send |
| Поле | Тип | Что содержит |
|---|---|---|
id |
string | Идентификатор для поля model в /send |
name |
string | Человекочитаемое название |
description |
string | Чем эта модель отличается от остальных |
isAvailable |
bool | Ключевое поле. Модель включена на сервере. Берите только такие — остальные отключены. |
isLocal |
bool | Модель работает на сервере Atlorium: переписка не уходит наружу |
maxInputTokens |
int | Лимит входа — с ним сравнивают длину текста до отправки. Единственный лимит длины сообщения |
maxOutputTokens |
int | Максимальная длина ответа. Рассуждения модели перед ответом расходуют этот же лимит |
contextWindowTokens |
int | Размер контекстного окна: вход + история + ответ |
maxTokens |
int | Устаревший алиас contextWindowTokens. Оставлен, чтобы не ломать старых клиентов; в новом коде используйте contextWindowTokens и maxInputTokens |
inputPricePer1kTokens |
number | Цена входных токенов этой модели, кредитов за 1000. 0 — токены модели не тарифицируются |
outputPricePer1kTokens |
number | Цена выходных токенов, кредитов за 1000. Обычно выше входной |
freeQuotaEligible |
bool | Покрывает ли запросы к этой модели дневная квота тарифа |
| Поле | Тип | Что содержит |
|---|---|---|
sessionId |
string | Идентификатор сессии. Передайте его в следующий /send — модель увидит предыдущие сообщения |
reply |
string | Ответ модели. На демо-ключе — заглушка, см. предупреждение выше |
model |
string | Какая модель фактически отвечала |
promptTokens |
int | Токенов ушло на запрос — по ним считается входная часть расхода |
completionTokens |
int | Токенов ушло на ответ — по ним считается выходная часть расхода. Если модель рассуждает перед ответом, сюда входят и рассуждения: в reply они не попадают, но токены расходуют |
totalTokens |
int | Сумма promptTokens и completionTokens |
createdAt |
date-time | Время ответа, UTC |
| Поле | Тип | Что содержит |
|---|---|---|
sessionId |
string | Идентификатор сессии |
messageCount |
int | Сколько сообщений пользователя уже в сессии (максимум 50) |
createdAt |
date-time | Когда создана |
lastActivityAt |
date-time | Последняя активность. Через час простоя сессия удаляется |
| Код | Причина | Что делать |
|---|---|---|
400 |
Сообщение пустое, длиннее maxInputTokens выбранной модели или указана модель, которой нет в /models |
Сократить текст или взять id из /models. Проверка идёт до резервирования денег |
401 |
Ключ отсутствует, просрочен или недействителен | Проверьте заголовок Authorization |
402 |
На балансе не хватает на удержание (см. «Цены и лимиты») | Пополнить на atlorium.com |
404 |
Сессия не найдена или истекла | Штатный случай: сессия живёт час. Начните новую с sessionId: null |
429 |
Превышен rate-limit | Подождать и повторить — но с потолком ожидания, см. ниже |
500 |
Сбой при обработке: модель не ответила за 10 минут, вернула ответ без текста, ИИ-сервис недоступен; либо в сессии уже 50 сообщений пользователя | Повторить позже, сузить вопрос или взять другую модель; при лимите сессии — начать новую (sessionId: null). За 500 деньги не списываются: удержание переводится в списание только после ответа модели с текстом |
503 |
Выбранная модель временно недоступна (isAvailable: false) либо идут плановые работы |
Взять другую модель из /models; при плановых работах — повторить позже, в message есть ссылка на страницу статуса. Деньги не списываются |
Во всех шести примерах коды разложены в человекочитаемые причины — смотрите класс AtloriumError.
Про 429 и Retry-After. Исчерпав часовой лимит, сервер честно просит подождать 40+ минут. Клиент, который слепо спит столько, сколько попросили, зависает на всё это время. Поэтому в примерах есть потолок MAX_RETRY_DELAY = 120 секунд: дольше не ждём, а честно сообщаем «квота исчерпана» и выходим. Повтор — ровно один раз.
/send отдаёт ответ целиком, а не потоком: пока модель не допишет последний токен, клиент не получает ничего. Перед ответом модель ещё и рассуждает. Короткий ответ приходит за секунды, развёрнутый ответ сильной модели — за несколько минут.
-
Таймаут HTTP-клиента — не меньше 10 минут. Таймауты библиотек по умолчанию обычно короче и оборвут длинный ответ на полпути. В примерах таймаут выставлен в 10 минут.
-
Обрыв соединения с вашей стороны запрос не отменяет. Модель допишет ответ, он сохранится в истории сессии, и запрос будет оплачен как выполненный. Отправить тот же вопрос заново — значит оплатить второй запрос. Текст оборванного ответа через API уже не получить (
GET /sessionотдаёт только сведения о сессии), но если продолжить диалог с тем жеsessionId, модель этот ответ учтёт. -
Не тарифицируются только сбои, и оба приходят кодом
500:- модель не ответила за 10 минут;
- модель вернула ответ без текста — например, потратила весь лимит ответа (
maxOutputTokens) на рассуждения. Помогает сузить вопрос или взять другую модель.
В обоих случаях удержание снимается целиком, а вопрос в историю сессии не попадает.
Демо-ключ отвечает сразу: реальная модель на нём не вызывается, поэтому время ответа в песочнице не проверить.
Оплата pay-as-you-go, без подписки: платите за выполненные запросы к /send. /models и операции с сессиями не тарифицируются.
Выполненным считается запрос, на который модель вернула текст, — даже если ваш клиент к этому моменту оборвал соединение. Сбои (500) не оплачиваются; подробнее — в разделе «Время ответа и таймауты».
Стоимость одного /send складывается из двух частей:
- ставка за запрос — одинаковая для всех моделей;
- стоимость токенов выбранной модели — зависит от модели и от длины диалога. У модели с
inputPricePer1kTokensиoutputPricePer1kTokens, равными нулю, эта часть отсутствует, и вы платите только за запрос. Считается по фактическимpromptTokens/completionTokensиз ответа.
Как это выглядит на балансе. Стоимость токенов известна только после ответа модели, а зарезервировать деньги нужно до. Поэтому перед вызовом удерживается максимально возможная стоимость запроса (весь допустимый ввод плюс самый длинный ответ), а списывается фактическая — остаток удержания возвращается сразу. Следствие: чтобы начать запрос к дорогой модели, на балансе должен лежать этот максимум, даже если спишется меньше. Не хватает на удержание — 402.
Поле freeQuotaEligible в /models показывает, покрывает ли запросы к модели дневная квота тарифа.
Актуальные цены: atlorium.com/pricing
Лимиты у этого сервиса самые жёсткие в Atlorium — за каждым вызовом стоит реальная работа модели и реальные токены. Величина лимита одинакова для демо-ключа и для зарегистрированного пользователя — песочница честно показывает те условия, которые вы получите в бою. Разница только в том, как он считается: у демо-ключа — по IP (ключ общий на всех), у боевого — на ваш аккаунт.
Один прогон примера = один платный вызов /send. Это сделано намеренно: пример не гоняет API в цикле. Учитывайте это, если запускаете его несколько раз подряд — 429 наступит быстро и это не поломка, а работающий лимит.
Какую модель выбрать? Ту, у которой isAvailable: true — и не зашивайте id в код. Состав доступных моделей задаётся конфигурацией сервера и меняется. Именно поэтому примеры сначала читают /models, а не хардкодят модель.
Что такое модель «Приватная» (isLocal: true)? Модель, которая работает на сервере Atlorium: переписка остаётся внутри периметра. Это важно, когда в тексте персональные данные или коммерческая тайна.
Как сделать чат-бот с памятью? Возьмите sessionId из ответа /send и передайте его в следующий /send. Модель увидит предыдущие сообщения. В одной сессии — до 50 сообщений пользователя, сессия живёт час с последней активности, потом удаляется. Стереть раньше — DELETE /api/AiChat/session/{id}.
Почему ответ идёт так долго и что будет, если не дождаться? Ответ приходит целиком, а перед ним модель рассуждает — развёрнутый ответ может идти несколько минут. Ставьте таймаут клиента не меньше 10 минут: если оборвать соединение раньше, модель всё равно допишет ответ, и запрос будет оплачен. Бесплатны только сбои — модель не ответила за 10 минут или вернула ответ без текста (оба случая — 500).
Как посчитать токены заранее? Точно — никак, токенизация зависит от модели. Практичная эвристика: символы / 4. Для английского она близка к правде, для русского обычно занижает. Её задача — не посчитать биллинг, а отсечь заведомо длинный текст до платного вызова. Именно так это и сделано в примерах.
Сколько текста можно отправить за раз? Лимит задаётся в токенах и зависит от модели — это поле maxInputTokens в /models, и у разных моделей оно разное. Единого лимита «в символах» у сервиса нет: сверяйтесь именно с maxInputTokens выбранной модели (400, если больше). Больший объём нужно резать на части и суммаризировать по кускам.
Чем это удобнее, чем поднимать ИИ-доступ отдельно? Тот же ключ, что и у остальных API Atlorium, единый счёт, оплата в рублях, никакой отдельной регистрации. Плюс сервер сам держит историю сессии — её не нужно тащить в каждом запросе.
Обязательна ли регистрация, чтобы попробовать? Нет. Демо-ключ публичный и работает без аккаунта — но reply он возвращает заглушкой, а не ответом модели.
Тем же ключом и из того же аккаунта:
- Распознавание текста с картинки — OCR по изображению или Base64
- Проверка почты — синтаксис, MX-записи, одноразовые адреса
- ЕГРЮЛ/ЕГРИП — проверка контрагента по ИНН/ОГРН: статус, адрес, капитал
- Валидация телефона — формат, тип номера, оператор диапазона
- Модерация изображений — содержимое, предметы и текст НА изображении
- Стандартизация адреса — разбор строки на компоненты и оценка качества
Полный каталог — atlorium.com
- Документация API (Swagger): atlorium.com/aiAPI
- Описание сервиса: atlorium.com/aiDescription
- Веб-интерфейс: atlorium.com/aiGUI
- OpenAPI-спецификация: aichat_ru.json
- Поддержка: support@atlorium.com
MIT — берите код и используйте как хотите, в том числе в коммерческих проектах.