Интеграция≈ 6 мин чтения

Telegram-бот + NeuroAPI: aiogram и OpenAI SDK

Рабочая схема Telegram-бота на Python: токен от BotFather, ключ NeuroAPI в окружении, асинхронный OpenAI-клиент и честные ограничения стриминга.

Короткий ответ

Краткий ответ

Telegram-бот на Python с NeuroAPI: токен бота от BotFather, ключ NeuroAPI в переменных, AsyncOpenAI с base_url https://neuroapi.host/v1, лимиты и деплой.

98

моделей в каталоге

Публичный каталог /price на 18.10.2026; список для бота можно получать через GET /v1/models.

/v1

базовый адрес

https://neuroapi.host/v1 — параметр base_url в клиенте OpenAI.

3

тарифа доступа

Пилот, Смарт и Оптимальный выбираются при создании ключа под бота.

/docs

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

Быстрый старт, форматы API и ошибки — neuroapi.host/docs (проверено 19.10.2026).

Два разных секрета

Токен бота выдаёт BotFather, ключ API — кабинет NeuroAPI. Это разные системы, и хранить их нужно раздельно.

AsyncOpenAI

Асинхронный клиент OpenAI подходит для aiogram: запрос к модели не блокирует обработку других сообщений.

base_url один раз

Адрес https://neuroapi.host/v1 задаётся при создании клиента; дальше используется обычный Chat Completions.

Лимиты — на стороне бота

НейроАПИ тарифицирует запросы, а ограничения на пользователя и частоту сообщений настраиваются в вашем боте.

Как поднять Telegram-бота на NeuroAPI

  1. 1

    Получите токен бота и ключ API

    Создайте бота у BotFather и сохраните токен. В кабинете NeuroAPI создайте API-ключ и выберите тариф. Оба секрета положите в переменные окружения.

  2. 2

    Установите зависимости

    Создайте виртуальное окружение и установите aiogram и openai: pip install aiogram openai. Версии фиксируйте в requirements.txt, чтобы деплой был воспроизводимым.

  3. 3

    Создайте клиент и обработчик

    Инициализируйте AsyncOpenAI с base_url https://neuroapi.host/v1 и ключом NeuroAPI, а в обработчике сообщений вызывайте chat.completions.create с точным ID модели.

  4. 4

    Добавьте лимиты и учёт расхода

    Ограничьте длину истории и число запросов на пользователя, сохраняйте usage из ответа. Ошибки 401, 404, 429 разбирайте по коду ответа.

  5. 5

    Запустите как сервис

    Настройте автоперезапуск и логирование без приватного текста. Для продакшена рассмотрите webhook, для отладки достаточно long polling.

Шаги и их текст совпадают с HowTo-разметкой. Названия классов aiogram и параметры OpenAI SDK сверены с официальной документацией 19.10.2026; порядок запуска проверяйте по актуальной версии библиотек.

Как устроен бот: Telegram и NeuroAPI

Бот — это ваш сервис, который принимает обновления от Telegram Bot API и отправляет запросы к модели через API NeuroAPI. В этой цепочке два независимых секрета: токен бота (его выдаёт BotFather) и ключ NeuroAPI (его создаёт пользователь в кабинете). Токен бота даёт доступ к переписке и отправке сообщений, ключ — к оплаченным запросам модели; смешивать их нельзя.

Запрос к модели выполняется по OpenAI-совместимому протоколу, поэтому подходит официальный клиент SDK. Ключевые поля: base_url с адресом NeuroAPI, api_key с ключом и model с точным ID из каталога. Ответ приходит в обычном формате Chat Completions, а поле usage позволяет учитывать расход на каждого пользователя.

  • BOT_TOKEN — только для Telegram Bot API.
  • NEUROAPI_API_KEY — только для запросов к модели.
  • base_url = https://neuroapi.host/v1.
  • model — точный ID из /price или GET /v1/models.

Минимальный бот на aiogram и AsyncOpenAI

Документация aiogram описывает типовую структуру: Dispatcher, обработчики команд и текстовых сообщений, запуск через start_polling. Модель вызывается внутри обработчика асинхронным клиентом SDK — это важно, потому что генерация занимает секунды, и синхронный вызов заблокировал бы бота для остальных пользователей.

Историю диалога храните самостоятельно: Chat Completions не помнит предыдущие сообщения. Для простого бота достаточно передавать последние несколько реплик, а для полноценного диалога — хранить контекст по chat_id с ограничением длины. Бесконечно растущая история увеличивает и задержку, и стоимость запроса.

  • Модель вызывается внутри async-обработчика.
  • Клиент создаётся один раз при старте, а не на каждое сообщение.
  • История — ваша ответственность, ограничивайте её длину.
  • Длинные ответы можно разбивать на несколько сообщений Telegram.

Стриминг в Telegram: честные ограничения

Стриминг выглядит эффектно, но Telegram не предназначен для десятков мелких правок одного сообщения. Редактирование отправленного сообщения — отдельный вызов Bot API, и при слишком частых правках вы получите ограничение со стороны Telegram (код 429 и время ожидания). Практичный компромисс: показывать индикатор «печатает» и обновлять сообщение раз в одну-две секунды, а не на каждый фрагмент.

Если задача — просто ответить по существу, надёжнее не стримить вовсе: дождаться полного ответа и отправить один раз. Это экономит вызовы Telegram, упрощает обработку ошибок и снижает риск получить 429. Стриминг стоит включать только там, где задержка первого токена действительно важна пользователю.

  • Не редактируйте сообщение на каждый фрагмент.
  • Обновляйте текст с паузой в одну-две секунды.
  • При 429 от Telegram — подождите время из ответа.
  • Для простых сценариев стриминг не нужен вовсе.

Лимиты, безопасные повторы и расход

Ошибки модели разбирайте по коду: 401 — неверный или отозванный ключ NeuroAPI, 404 — опечатка в ID модели, 429 — превышение лимитов, 5xx — временная проблема. Повторы допустимы для 429 и 5xx с ограничением числа попыток и задержкой; при 401 и 404 повтор не поможет, нужна правка конфигурации.

Расход зависит от модели, длины истории и числа ответов. Ведите учёт по пользователям: сохраняйте usage из ответов и ограничивайте длину контекста. Баланс предоплаченный — если он закончился, запросы перестанут выполняться, поэтому для production-бота заведите мониторинг остатка и уведомление администратору.

  • 401 и 404 не лечатся повтором — проверьте ключ и модель.
  • 429 и 5xx — повтор с задержкой и ограничением попыток.
  • Сохраняйте usage и считайте расход по пользователям.
  • Следите за балансом: он предоплаченный.

Деплой, секреты и поддержка

Запускать бота лучше как отдельный сервис с автоперезапуском: systemd, Docker или платформа приложений. Токены передавайте через переменные окружения, а не в исходниках; если используется git, добавьте .env в .gitignore. Для продакшена удобнее webhook с HTTPS, для разработки — long polling, как в примере из документации aiogram.

Перед запуском на пользователей проверьте четыре сценария: обычный ответ, длинный ответ, ошибка ключа и превышение баланса. Логи должны содержать идентификатор пользователя, модель и usage, но не полный текст приватных сообщений. Документация и коды ошибок NeuroAPI помогут разбирать инциденты без догадок. Отдельно зафиксируйте, кто получает уведомление при исчерпании баланса и как быстро бот должен деградировать до понятного сообщения.

  • Автоперезапуск процесса обязателен для бота.
  • Секреты — только в переменных окружения.
  • Проверьте штатный, длинный и ошибочный сценарии.
  • Логи без приватного текста, но с usage и моделью.

Минимальный бот: aiogram + AsyncOpenAI

python
import asyncio
import os

from aiogram import Bot, Dispatcher
from aiogram.filters import CommandStart
from aiogram.types import Message
from openai import AsyncOpenAI

BOT_TOKEN = os.environ["BOT_TOKEN"]
MODEL_ID = os.environ["NEUROAPI_MODEL"]

client = AsyncOpenAI(
    base_url="https://neuroapi.host/v1",
    api_key=os.environ["NEUROAPI_API_KEY"],
)

dp = Dispatcher()

@dp.message(CommandStart())
async def start(message: Message) -> None:
    await message.answer("Привет! Задайте вопрос модели.")

@dp.message()
async def answer(message: Message) -> None:
    response = await client.chat.completions.create(
        model=MODEL_ID,
        messages=[{"role": "user", "content": message.text}],
        max_tokens=800,
    )
    await message.answer(response.choices[0].message.content)

async def main() -> None:
    bot = Bot(token=BOT_TOKEN)
    await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())

Переменные окружения

bash
BOT_TOKEN=<токен_от_BotFather>
NEUROAPI_API_KEY=<ключ_из_кабинета_NeuroAPI>
NEUROAPI_MODEL=<MODEL_ID_ИЗ_PRICE>

Запустите бота на рублёвом балансе

Один ключ NeuroAPI, OpenAI-совместимый base_url и каталог моделей в рублях. Начните с короткого ответа в тестовом боте, а лимиты и мониторинг добавьте до запуска на пользователей.

Создать ключ и начатьБыстрый старт

Факты о каталоге проверены 18.10.2026; API aiogram и openai описаны по официальной документации на 19.10.2026.