neogram

neogram — это Python-модуль, объединяющий в себе клиент для Telegram Bot API (версия 10.0) и набор клиентов для различных AI-сервисов. Модуль построен поверх curl_cffi для обхода TLS-фингерпринтинга и обеспечивает полную типизацию через dataclass.

Установка

pip install neogram

Зависимости

curl_cffi — HTTP-клиент с поддержкой имперсонации браузерных TLS-фингерпринтов
beautifulsoup4 — парсинг HTML (для перевода Google Translate в классе Deef)

Структура модуля

neogram/
├── __init__.py      # Публичный API: реэкспорт всех классов
├── fgram.py         # Telegram Bot API клиент (Bot, AsyncBot, типы Telegram)
└── ii.py            # AI-клиенты (OnlySQ, Deef, Qwen, ChatGPT/OpenAI)

Содержание

Telegram Bot API (fgram)
AI-клиенты (ii)
- OnlySQ
- Deef
- Qwen
- ChatGPT / OpenAI

Telegram Bot API (fgram)

Модуль fgram.py предоставляет полную реализацию Telegram Bot API версии 10.0, включая синхронный (Bot) и асинхронный (AsyncBot) клиенты, автоматическую сериализацию/десериализацию всех типов Telegram и декораторную систему обработчиков обновлений.

Bot — синхронный клиент

from neogram import Bot

bot = Bot(
    token="123456:ABC-DEF...",
    api_url="https://api.telegram.org", # по умолчанию
    timeout=60,  # HTTP-таймаут (секунды)
    impersonate="chrome", # TLS-фингерпринт curl_cffi
    parse_mode=None, # "HTML" или "MarkdownV2"
    proxies=None, # {"http": "...", "https": "..."}
    max_retries=3, # число автоповторов при ошибках транспорта
    retry_on_flood=True, # автоповтор при 429 Flood
)

Параметры конструктора:

Параметр	Тип	По умолчанию	Описание
`token`	`str`	—	Токен бота от @BotFather (обязательный)
`api_url`	`str`	`https://api.telegram.org`	Базовый URL Telegram API
`timeout`	`int`	`60`	HTTP-таймаут запроса в секундах
`impersonate`	`str`	`"chrome"`	TLS-фингерпринт для `curl_cffi` (например `"chrome"`, `"safari"`)
`parse_mode`	`Optional[str]`	`None`	Режим форматирования по умолчанию (`"HTML"`, `"MarkdownV2"`)
`proxies`	`Optional[dict]`	`None`	Словарь прокси-настроек для `curl_cffi`
`max_retries`	`int`	`3`	Максимальное число автоматических повторов при транспортных ошибках и ошибках сервера
`retry_on_flood`	`bool`	`True`	Автоматический повтор при ошибке 429 (Flood)

Особенности транспорта:

Использует curl_cffi.requests.Session с имперсонацией браузерного TLS-фингерпринта
Автоматический retry при транспортных ошибках (с exponential backoff до 30 сек)
Автоматический retry при 429 Flood (ожидание retry_after + 1 сек)
Автоматический retry при серверных ошибках 5xx (с exponential backoff)

AsyncBot — асинхронный клиент

from neogram import AsyncBot

async with AsyncBot(token="123456:ABC-DEF...") as bot:
    me = await bot.get_me()
    await bot.send_message(chat_id=123, text="Hello!")

Наследуется от Bot и предоставляет асинхронные версии всех API-методов. Все методы-корутины — используйте await. Поддерживает асинхронный контекстный менеджер (async with).

Ключевые отличия от синхронного Bot:

Использует curl_cffi.requests.AsyncSession вместо Session
Все API-методы являются корутинами (async def)
Обработчики могут быть как синхронными, так и асинхронными — диспетчер автоматически определяет и awaitит результат
Метод aclose() для корректного закрытия сессии
Polling и process_update также асинхронны

Система обработчиков (handlers)

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

Декораторы обработчиков

Декоратор	Тип обновления	Аргументы фильтрации
`@bot.message_handler(...)`	`message`	`commands`, `content_types`, `regexp`, `func`, `chat_types`, `user_ids`, `chat_ids`
`@bot.edited_message_handler(...)`	`edited_message`	`commands`, `content_types`, `regexp`, `func`, `chat_types`, `user_ids`, `chat_ids`
`@bot.channel_post_handler(...)`	`channel_post`	`commands`, `content_types`, `regexp`, `func`, `chat_types`, `chat_ids`
`@bot.edited_channel_post_handler(...)`	`edited_channel_post`	`commands`, `content_types`, `regexp`, `func`, `chat_types`
`@bot.callback_query_handler(...)`	`callback_query`	`func`, `data`
`@bot.inline_handler(...)`	`inline_query`	`func`, `regexp`
`@bot.my_chat_member_handler(...)`	`my_chat_member`	`func`
`@bot.chat_member_handler(...)`	`chat_member`	`func`
`@bot.chat_join_request_handler(...)`	`chat_join_request`	`func`
`@bot.poll_handler(...)`	`poll`	`func`
`@bot.poll_answer_handler(...)`	`poll_answer`	`func`
`@bot.pre_checkout_query_handler(...)`	`pre_checkout_query`	`func`
`@bot.shipping_query_handler(...)`	`shipping_query`	`func`
`@bot.business_message_handler(...)`	`business_message`	`commands`, `content_types`, `regexp`, `func`
`@bot.edited_business_message_handler(...)`	`edited_business_message`	`commands`, `content_types`, `regexp`, `func`
`@bot.deleted_business_messages_handler(...)`	`deleted_business_messages`	`func`
`@bot.chosen_inline_result_handler(...)`	`chosen_inline_result`	`func`
`@bot.message_reaction_handler(...)`	`message_reaction`	`func`
`@bot.message_reaction_count_handler(...)`	`message_reaction_count`	`func`
`@bot.chat_boost_handler(...)`	`chat_boost`	`func`
`@bot.removed_chat_boost_handler(...)`	`removed_chat_boost`	`func`
`@bot.purchased_paid_media_handler(...)`	`purchased_paid_media`	`func`

Обработчик ошибок

@bot.error_handler
def on_error(update, exception):
    print(f"Ошибка: {exception}")

Программная регистрация

bot.register_handler("message", my_handler, commands=["start"], chat_types=["private"])

Фильтрация обработчиков

Фильтры передаются в декоратор и проверяются при диспетчеризации обновлений. Обновление проходит, только если все фильтры совпадают.

Фильтр	Тип	Описание
`commands`	`Optional[List[str]]`	Список команд (без `/`). Проверяет, что текст начинается с `/команда`
`content_types`	`Optional[List[str]]`	Тип контента сообщения (`"text"`, `"photo"`, `"document"` и т.д.)
`regexp`	`Optional[str]`	Regex-паттерн для проверки `message.text` или `message.caption`
`func`	`Optional[Callable]`	Произвольная функция-предикат, принимает объект обновления
`chat_types`	`Optional[List[str]]`	Тип чата (`"private"`, `"group"`, `"supergroup"`, `"channel"`)
`user_ids`	`Optional[List[int]]`	Белый список ID пользователей
`chat_ids`	`Optional[List[int]]`	Белый список ID чатов
`data`	`Optional[Union[str, Callable]]`	Для callback_query — точное совпадение или regex для `callback_query.data`

StopPropagation: выбросьте StopPropagation внутри обработчика, чтобы остановить дальнейшую обработку текущего обновления.

Polling и Webhook

Polling (long polling)

# Синхронный
bot.polling(timeout=30, none_stop=True, interval=0.0)

# Бесконечный polling (none_stop=True по умолчанию)
bot.infinity_polling()

# Остановка polling
bot.stop_polling()

Параметр	Тип	По умолчанию	Описание
`timeout`	`int`	`30`	Таймаут long polling в секундах
`allowed_updates`	`Optional[List[str]]`	`None`	Список типов обновлений для получения
`none_stop`	`bool`	`True`	Не останавливаться при ошибках API
`interval`	`float`	`0.0`	Задержка между запросами (секунды)

Webhook

# Синхронный
@app.post("/webhook")
def webhook():
    bot.process_update(request.json)
    return "ok"

# Асинхронный
@app.post("/webhook")
async def webhook():
    await bot.process_update(request.json)
    return "ok"

Исключения

`TelegramAPIError` (алиас: `TelegramError`)

Выбрасывается при ошибке от Telegram API.

Атрибут	Тип	Описание
`error_code`	`int`	HTTP-подобный код ошибки (400, 401, 403, 429, 500 и т.д.)
`description`	`str`	Человекочитаемое описание ошибки
`parameters`	`dict`	Дополнительные параметры (например `{"retry_after": 30}`)
`method`	`str`	Имя API-метода, вызвавшего ошибку
`retry_after`	`Optional[int]`	Удобный shortcut для `parameters.get("retry_after")`

`StopPropagation`

Выбросьте внутри обработчика, чтобы остановить диспетчеризацию дальнейших обработчиков для текущего обновления.

TelegramObject — базовый класс типов

Все типы Telegram API наследуются от TelegramObject (dataclass) и предоставляют:

from_dict(data: dict) -> TelegramObject — десериализация из JSON (автоматическое переименование полей: type → type_val, from → from_user и т.д.)
to_dict() -> dict — сериализация в JSON (обратное переименование)
Автоматический dispatch union-типов — полиморфные поля (например MessageOrigin, ChatMember) автоматически десериализуются в правильный подкласс на основе поля-дискриминатора

InputFile — загрузка файлов

from neogram import InputFile

# Из пути к файлу
f1 = InputFile("/path/to/photo.jpg")

# Из байтов
f2 = InputFile(b"raw bytes data", filename="document.pdf")

# Из файлового объекта
with open("audio.mp3", "rb") as fh:
    f3 = InputFile(fh)

# Использование
bot.send_document(chat_id=123, document=InputFile("/path/to/file.pdf"))

API-методы Bot

Ниже приведён полный список API-методов, доступных в Bot (синхронно) и AsyncBot (асинхронно с await). Все методы возвращают типизированные объекты Telegram.

Обновления и подключение

Метод	Возвращает	Описание
`get_updates(offset, limit, timeout, allowed_updates)`	`List[Update]`	Получение обновлений через long polling
`set_webhook(url, certificate, ...)`	`bool`	Установка webhook
`delete_webhook(drop_pending_updates)`	`bool`	Удаление webhook
`get_webhook_info()`	`WebhookInfo`	Информация о текущем webhook
`get_me()`	`User`	Информация о боте
`log_out()`	`bool`	Выход из облачного Bot API
`close()`	`bool`	Закрытие экземпляра бота на локальном сервере

Отправка сообщений

Метод	Возвращает	Описание
`send_message(chat_id, text, ...)`	`Message`	Отправка текстового сообщения
`forward_message(chat_id, from_chat_id, message_id, ...)`	`MessageId`	Пересылка сообщения
`forward_messages(chat_id, from_chat_id, message_ids, ...)`	`List[MessageId]`	Пересылка нескольких сообщений
`copy_message(chat_id, from_chat_id, message_id, ...)`	`MessageId`	Копирование сообщения
`copy_messages(chat_id, from_chat_id, message_ids, ...)`	`List[MessageId]`	Копирование нескольких сообщений
`send_photo(chat_id, photo, ...)`	`Message`	Отправка фото
`send_audio(chat_id, audio, ...)`	`Message`	Отправка аудио
`send_document(chat_id, document, ...)`	`Message`	Отправка документа
`send_video(chat_id, video, ...)`	`Message`	Отправка видео
`send_animation(chat_id, animation, ...)`	`Message`	Отправка анимации (GIF)
`send_voice(chat_id, voice, ...)`	`Message`	Отправка голосового сообщения
`send_video_note(chat_id, video_note, ...)`	`Message`	Отправка видео-заметки (кружочек)
`send_live_photo(chat_id, live_photo, photo, ...)`	`Message`	Отправка живого фото
`send_paid_media(chat_id, star_count, media, ...)`	`Message`	Отправка платного медиа
`send_media_group(chat_id, media, ...)`	`List[Message]`	Отправка группы медиа
`send_location(chat_id, latitude, longitude, ...)`	`Message`	Отправка локации
`send_venue(chat_id, latitude, longitude, title, address, ...)`	`Message`	Отправка места
`send_contact(chat_id, phone_number, first_name, ...)`	`Message`	Отправка контакта
`send_poll(chat_id, question, options, ...)`	`Message`	Отправка опроса
`send_checklist(business_connection_id, chat_id, checklist, ...)`	`Message`	Отправка чек-листа
`send_dice(chat_id, ...)`	`Message`	Отправка кубика
`send_message_draft(chat_id, draft_id, ...)`	`Message`	Отправка черновика сообщения
`send_chat_action(chat_id, action, ...)`	`bool`	Отправка действия «печатает…»

Реакции и действия

Метод	Возвращает	Описание
`set_message_reaction(chat_id, message_id, reaction, is_big)`	`bool`	Установка реакции на сообщение

Редактирование и удаление

Метод	Возвращает	Описание
`edit_message_text(text, ...)`	`Message`	Редактирование текста сообщения
`edit_message_caption(...)`	`Message`	Редактирование подписи к медиа
`edit_message_reply_markup(...)`	`Message`	Редактирование inline-клавиатуры
`delete_message(chat_id, message_id)`	`bool`	Удаление сообщения
`delete_messages(chat_id, message_ids)`	`bool`	Удаление нескольких сообщений
`delete_message_reaction(chat_id, message_id, ...)`	`bool`	Удаление реакции

Ответы на запросы

Метод	Возвращает	Описание
`answer_callback_query(callback_query_id, ...)`	`bool`	Ответ на callback-запрос
`answer_inline_query(inline_query_id, results, ...)`	`bool`	Ответ на inline-запрос
`answer_guest_query(guest_query_id, result)`	`bool`	Ответ на guest-запрос

Профили пользователей

Метод	Возвращает	Описание
`get_user_profile_photos(user_id, ...)`	`UserProfilePhotos`	Фото профиля пользователя
`get_user_profile_audios(user_id, ...)`	`UserProfileAudios`	Аудио профиля пользователя
`set_user_emoji_status(user_id, ...)`	`bool`	Установка emoji-статуса

Файлы

Метод	Возвращает	Описание
`get_file(file_id)`	`File`	Получение информации о файле

Чаты: администрирование участников

Метод	Возвращает	Описание
`ban_chat_member(chat_id, user_id, ...)`	`bool`	Бан участника
`unban_chat_member(chat_id, user_id, ...)`	`bool`	Разбан участника
`restrict_chat_member(chat_id, user_id, permissions, ...)`	`bool`	Ограничение участника
`promote_chat_member(chat_id, user_id, ...)`	`bool`	Повышение участника
`set_chat_administrator_custom_title(...)`	`bool`	Установка кастомного титула админа
`set_chat_member_tag(chat_id, user_id, tag)`	`bool`	Установка тега участника
`ban_chat_sender_chat(chat_id, sender_chat_id)`	`bool`	Бан канала-отправителя
`unban_chat_sender_chat(chat_id, sender_chat_id)`	`bool`	Разбан канала-отправителя

Чаты: настройки

Метод	Возвращает	Описание
`set_chat_permissions(chat_id, permissions, ...)`	`bool`	Установка прав чата
`export_chat_invite_link(chat_id)`	`str`	Экспорт ссылки-приглашения
`create_chat_invite_link(chat_id, ...)`	`ChatInviteLink`	Создание ссылки-приглашения
`edit_chat_invite_link(chat_id, invite_link, ...)`	`ChatInviteLink`	Редактирование ссылки-приглашения
`create_chat_subscription_invite_link(...)`	`ChatInviteLink`	Создание платной подписки
`edit_chat_subscription_invite_link(...)`	`ChatInviteLink`	Редактирование платной подписки
`revoke_chat_invite_link(chat_id, invite_link)`	`ChatInviteLink`	Отзыв ссылки-приглашения
`approve_chat_join_request(chat_id, user_id)`	`bool`	Одобрение заявки на вступление
`decline_chat_join_request(chat_id, user_id)`	`bool`	Отклонение заявки на вступление
`set_chat_photo(chat_id, photo)`	`bool`	Установка фото чата
`delete_chat_photo(chat_id)`	`bool`	Удаление фото чата
`set_chat_title(chat_id, title)`	`bool`	Установка названия чата
`set_chat_description(chat_id, description)`	`bool`	Установка описания чата
`pin_chat_message(chat_id, message_id, ...)`	`bool`	Закрепление сообщения
`unpin_chat_message(chat_id, ...)`	`bool`	Открепление сообщения
`unpin_all_chat_messages(chat_id)`	`bool`	Открепление всех сообщений
`leave_chat(chat_id)`	`bool`	Выход из чата
`get_chat(chat_id)`	`ChatFullInfo`	Получение информации о чате
`get_chat_administrators(chat_id, ...)`	`List[ChatMember]`	Список администраторов
`get_chat_member_count(chat_id)`	`Any`	Количество участников
`get_chat_member(chat_id, user_id)`	`ChatMember`	Информация об участнике
`get_user_personal_chat_messages(user_id, limit)`	`List[Message]`	Личные сообщения пользователя

Форумы (топики)

Метод	Возвращает	Описание
`get_forum_topic_icon_stickers()`	`List[Sticker]`	Стикеры для иконок топиков
`create_forum_topic(chat_id, name, ...)`	`ForumTopic`	Создание топика
`edit_forum_topic(chat_id, message_thread_id, ...)`	`bool`	Редактирование топика
`close_forum_topic(chat_id, message_thread_id)`	`bool`	Закрытие топика
`reopen_forum_topic(chat_id, message_thread_id)`	`bool`	Повторное открытие топика
`delete_forum_topic(chat_id, message_thread_id)`	`bool`	Удаление топика
`unpin_all_forum_topic_messages(...)`	`bool`	Открепление всех сообщений в топике
`edit_general_forum_topic(chat_id, name)`	`bool`	Редактирование общего топика
`close_general_forum_topic(chat_id)`	`bool`	Закрытие общего топика
`reopen_general_forum_topic(chat_id)`	`bool`	Повторное открытие общего топика
`hide_general_forum_topic(chat_id)`	`bool`	Скрытие общего топика
`unhide_general_forum_topic(chat_id)`	`bool`	Отображение общего топика
`unpin_all_general_forum_topic_messages(chat_id)`	`bool`	Открепление всех сообщений общего топика

Команды бота и настройки

Метод	Возвращает	Описание
`set_my_commands(commands, scope, language_code)`	`bool`	Установка команд бота
`delete_my_commands(scope, language_code)`	`bool`	Удаление команд бота
`get_my_commands(scope, language_code)`	`List[BotCommand]`	Получение команд бота
`set_my_name(name, language_code)`	`bool`	Установка имени бота
`get_my_name(language_code)`	`BotName`	Получение имени бота
`set_my_description(description, language_code)`	`bool`	Установка описания бота
`get_my_description(language_code)`	`BotDescription`	Получение описания бота
`set_my_short_description(...)`	`bool`	Установка краткого описания
`get_my_short_description(language_code)`	`BotShortDescription`	Получение краткого описания
`set_my_profile_photo(photo)`	`bool`	Установка фото профиля бота
`remove_my_profile_photo()`	`bool`	Удаление фото профиля бота
`set_chat_menu_button(chat_id, menu_button)`	`bool`	Установка кнопки меню
`get_chat_menu_button(chat_id)`	`MenuButton`	Получение кнопки меню
`set_my_default_administrator_rights(...)`	`bool`	Установка прав админа по умолчанию
`get_my_default_administrator_rights(...)`	`ChatAdministratorRights`	Получение прав админа по умолчанию

Подарки и верификация

Метод	Возвращает	Описание
`get_available_gifts()`	`Gifts`	Список доступных подарков
`send_gift(gift_id, ...)`	`bool`	Отправка подарка
`gift_premium_subscription(user_id, ...)`	`bool`	Подарок Premium-подписки
`verify_user(user_id, ...)`	`bool`	Верификация пользователя
`verify_chat(chat_id, ...)`	`bool`	Верификация чата
`remove_user_verification(user_id)`	`bool`	Снятие верификации пользователя
`remove_chat_verification(chat_id)`	`bool`	Снятие верификации чата

Бизнес-подключения

Метод	Возвращает	Описание
`get_business_connection(business_connection_id)`	`BusinessConnection`	Информация о бизнес-подключении
`read_business_message(...)`	`bool`	Чтение бизнес-сообщения
`delete_business_messages(...)`	`bool`	Удаление бизнес-сообщений
`set_business_account_name(...)`	`bool`	Установка имени бизнес-аккаунта
`set_business_account_username(...)`	`bool`	Установка имени пользователя бизнес-аккаунта
`set_business_account_bio(...)`	`bool`	Установка био бизнес-аккаунта
`set_business_account_profile_photo(...)`	`bool`	Установка фото бизнес-аккаунта
`remove_business_account_profile_photo(...)`	`bool`	Удаление фото бизнес-аккаунта
`set_business_account_gift_settings(...)`	`bool`	Настройки подарков бизнес-аккаунта
`get_business_account_star_balance(...)`	`StarAmount`	Баланс звёзд бизнес-аккаунта
`transfer_business_account_stars(...)`	`bool`	Перевод звёзд
`get_business_account_gifts(...)`	`OwnedGifts`	Список подарков бизнес-аккаунта

Управляемые боты

Метод	Возвращает	Описание
`get_managed_bot_token(user_id)`	`str`	Получение токена управляемого бота
`replace_managed_bot_token(user_id)`	`str`	Замена токена управляемого бота
`get_managed_bot_access_settings(user_id)`	`BotAccessSettings`	Настройки доступа управляемого бота
`set_managed_bot_access_settings(user_id, ...)`	`BotAccessSettings`	Установка настроек доступа

Boost, стикеры, звёзды, игры и другие

Метод	Возвращает	Описание
`get_user_chat_boosts(chat_id, user_id)`	`UserChatBoosts`	Boost-ы пользователя в чате
`set_chat_sticker_set(chat_id, sticker_set_name)`	`bool`	Установка набора стикеров
`delete_chat_sticker_set(chat_id)`	`bool`	Удаление набора стикеров

Полный список методов включает также все методы для работы со стикерами, звёздами (Star Transactions), играми, платными медиа, паспортными данными и др. — всего более 150 API-методов, соответствующих Bot API 10.0.

Типы Telegram API

Модуль определяет все типы Telegram Bot API 10.0 как dataclass-ы с _FIELD_META для автоматической сериализации. Ниже перечислены основные группы типов (полный список — в __all__ модуля):

Базовые: TelegramObject, Update, User, Chat, ChatFullInfo, Message, MessageId

Сообщения: MessageEntity, TextQuote, ExternalReplyInfo, ReplyParameters, MessageOrigin*, LinkPreviewOptions, InaccessibleMessage, MaybeInaccessibleMessage

Медиа: PhotoSize, Animation, Audio, Document, Video, VideoNote, Voice, LivePhoto, File, VideoQuality

Платные медиа: PaidMediaInfo, PaidMedia*, InputPaidMedia*

Опросы: Poll, PollOption, PollAnswer, PollMedia, InputPollOption, InputPollMedia, InputPollOptionMedia

Клавиатуры: InlineKeyboardMarkup, InlineKeyboardButton, ReplyKeyboardMarkup, KeyboardButton, ReplyKeyboardRemove, ForceReply, KeyboardButtonRequestUsers, KeyboardButtonRequestChat, KeyboardButtonPollType

Inline: InlineQuery, InlineQueryResult*, InputMessageContent*, ChosenInlineResult

Чаты: ChatPermissions, ChatPhoto, ChatInviteLink, ChatAdministratorRights, ChatMember*, ChatJoinRequest, ChatLocation, ChatShared, ChatBackground

Реакции: ReactionType*, ReactionCount, MessageReactionUpdated, MessageReactionCountUpdated

Форумы: ForumTopic, ForumTopicCreated, ForumTopicEdited, ForumTopicClosed, ForumTopicReopened, GeneralForumTopic*

Подарки: Gift, Gifts, GiftInfo, GiftBackground, UniqueGift*, OwnedGift*, AcceptedGiftTypes

Бизнес: BusinessConnection, BusinessBotRights, BusinessIntro, BusinessLocation, BusinessOpeningHours*, BusinessMessagesDeleted

Boost: ChatBoost, ChatBoostSource*, ChatBoostUpdated, ChatBoostRemoved, UserChatBoosts

Платежи: Invoice, LabeledPrice, ShippingAddress, ShippingOption, ShippingQuery, OrderInfo, SuccessfulPayment, RefundedPayment, PreCheckoutQuery

Звёзды: StarAmount, StarTransaction, StarTransactions, TransactionPartner*, RevenueWithdrawalState*, AffiliateInfo

Паспорт: PassportData, PassportFile, EncryptedPassportElement, EncryptedCredentials, PassportElementError*

Игры: Game, CallbackGame, GameHighScore

Прочее: WebhookInfo, BotCommand, BotCommandScope*, BotName, BotDescription, BotShortDescription, MenuButton*, MaskPosition, Sticker, StickerSet, InputSticker, Story*, Dice, Contact, Venue, Location, ProximityAlertTriggered, WebAppData, WebAppInfo, SentWebAppMessage, WriteAccessAllowed, ResponseParameters, CallbackQuery

AI-клиенты (ii)

Модуль ii.py предоставляет набор клиентов для различных AI-сервисов. Все клиенты используют curl_cffi для HTTP-запросов с возможностью имперсонации браузерных TLS-фингерпринтов.

OnlySQ

Клиент API OnlySQ для генерации текста и изображений.

from neogram import OnlySQ

ai = OnlySQ(key="your-api-key")

`init(key: str)`

Параметр	Тип	Описание
`key`	`str`	API-ключ OnlySQ (получить: https://my.onlysq.ru/)

`get_models(modality, can_tools, can_think, can_stream, status, max_cost, return_names) -> List[str]`

Получает и фильтрует доступные модели OnlySQ.

Параметр	Тип	По умолчанию	Описание
`modality`	`Optional[Union[str, List[str]]]`	`None`	Модальность модели (фильтр)
`can_tools`	`Optional[bool]`	`None`	Поддержка tool calling
`can_think`	`Optional[bool]`	`None`	Поддержка режима размышлений
`can_stream`	`Optional[bool]`	`None`	Поддержка стриминга
`status`	`Optional[str]`	`None`	Статус модели
`max_cost`	`Optional[float]`	`None`	Максимальная стоимость
`return_names`	`bool`	`False`	Возвращать имена вместо ключей

`generate_answer(model, messages, timeout) -> str`

Генерация текстового ответа. Автоматический retry (3 попытки) при серверных ошибках 5xx с exponential backoff.

Параметр	Тип	По умолчанию	Описание
`model`	`str`	`"gpt-5.2-chat"`	Имя модели
`messages`	`Optional[List[dict]]`	`None`	Список сообщений (обязательный)
`timeout`	`int`	`120`	Таймаут запроса (секунды)

Возвращает: строку с текстом ответа или строку с ошибкой ("Error: ...").

`generate_image(model, prompt, ratio, filename) -> bool`

Генерация изображения.

Параметр	Тип	По умолчанию	Описание
`model`	`str`	`"flux"`	Имя модели генерации
`prompt`	`Optional[str]`	`None`	Текстовый промпт (обязательный)
`ratio`	`str`	`"16:9"`	Соотношение сторон
`filename`	`str`	`"image.png"`	Имя файла для сохранения

Возвращает: True при успешной генерации и сохранении, False при ошибке.

Deef

Набор утилит: перевод, сокращение ссылок, фоновые задачи, запросы к Perplexity AI, Toolbaz и DeepInfra.

from neogram import Deef

deef = Deef()

`translate(text, lang) -> str`

Перевод текста через Google Translate (мобильная версия).

Параметр	Тип	По умолчанию	Описание
`text`	`Optional[str]`	`None`	Текст для перевода
`lang`	`str`	`"en"`	Целевой язык

`short_url(long_url) -> str`

Сокращение ссылки через clck.ru.

Параметр	Тип	По умолчанию	Описание
`long_url`	`Optional[str]`	`None`	Длинная ссылка

`run_in_bg(func, *args, **kwargs) -> threading.Thread`

Запускает функцию в фоновом daemon-потоке. Возвращает объект Thread. Ошибки внутри функции логируются, но не пробрасываются.

`encode_base64(path) -> Optional[str]`

Кодирует содержимое файла в base64-строку.

Параметр	Тип	Описание
`path`	`Optional[str]`	Путь к файлу (обязательный)

`perplexity_ask(prompt, model) -> dict`

Запрос к Perplexity AI через SSE (Server-Sent Events). Автоматически получает конфигурацию моделей, выбирает подходящую и парсит потоковый ответ.

Параметр	Тип	По умолчанию	Описание
`prompt`	`Optional[str]`	`None`	Текст запроса (обязательный)
`model`	`str`	`"auto"`	Название модели (например `"o3pro"`, `"turbo"`, `"auto"`)

Возвращает:

При успехе: {"text": "ответ", "urls": ["url1", ...]}
При ошибке: {"text": "Error", "urls": []}

`toolchat(prompt, model) -> str`

Генерация ответа через Toolbaz. Автоматически получает токен и отправляет запрос.

Параметр	Тип	По умолчанию	Описание
`prompt`	`Optional[str]`	`None`	Текст запроса (обязательный)
`model`	`str`	`"toolbaz-v4.5-fast"`	Название модели

Доступные модели: gemini-3-flash, gemini-3.1-flash-lite, gemini-2.5-pro, gemini-2.5-flash, deepseek-v3.1, deepseek-v3, deepseek-r1, gpt-5.2, gpt-5, gpt-oss-120b, o3-mini, gpt-4o-latest, claude-sonnet-4, grok-4-fast, toolbaz-v4.5-fast, toolbaz-v4, Llama-4-Maverick

`deepinfra(messages, model, temperature, max_tokens, timeout) -> dict`

Чат-запрос к DeepInfra API.

Параметр	Тип	По умолчанию	Описание
`messages`	`List[dict]`	—	Список сообщений в формате OpenAI
`model`	`str`	`"zai-org/GLM-5.1"`	Идентификатор модели
`temperature`	`float`	`0.7`	Температура генерации (0.0–1.0)
`max_tokens`	`int`	`4000`	Максимальное число токенов в ответе
`timeout`	`int`	`30`	Таймаут запроса (секунды)

Возвращает: dict — JSON-ответ от DeepInfra при успехе, {"error": "..."} при ошибке.

Qwen

Клиент для работы с моделями Qwen через chat.qwen.ai. Поддерживает текст, изображения, поиск, deep research и другие режимы.

from neogram import Qwen

qwen = Qwen()

`init(proxy: Optional[str] = None)`

Параметр	Тип	По умолчанию	Описание
`proxy`	`Optional[str]`	`None`	URL прокси-сервера

`fetch_models() -> List[Dict]`

Возвращает список доступных моделей с кэшированием (TTL 10 минут). Каждая модель содержит поля: id, name, capabilities (vision, thinking, search), chat_types, thinking_format, is_visitor_active.

`chat(model, messages, stream, ctype, size, think) -> Union[str, Iterator]`

Чат с моделями Qwen. Поддерживает автоматическую загрузку изображений, смену модели при отсутствии vision-поддержки, и автопереключение режима чата.

Параметр	Тип	По умолчанию	Описание
`model`	`str`	`"qwen3.6-plus"`	Имя модели
`messages`	`Optional[List[dict]]`	`None`	Список сообщений в формате OpenAI
`stream`	`bool`	`False`	`True` — вернуть итератор чанков, `False` — полный ответ строкой
`ctype`	`str`	`"t2t"`	Режим чата: `t2t`, `search`, `t2i`, `deep_research`, `artifacts`, `learn`, `image_edit`
`size`	`Optional[str]`	`None`	Размер для t2i/image_edit (например `"16:9"`, `"9:16"`, `"1:1"`)
`think`	`bool`	`True`	Включить режим размышлений

Возвращает:

str — если stream=False
Iterator — если stream=True (yield str или dict с type="thinking" / type="image")

Поддерживаемые типы чата (ctype): t2t, search, t2i, deep_research, artifacts, learn, image_edit

Поддержка изображений: Если в последнем сообщении пользователя есть image_url, но модель не поддерживает vision, клиент автоматически переключится на vision-совместимую модель.

Гостевой режим: Клиент автоматически генерирует LZW-сжатые cookies (ssxmod_itna) и получает bx-umidtoken для авторизации запросов без аккаунта. При загрузке изображений используется Alibaba Cloud OSS через STS-токены.

ChatGPT / OpenAI

Универсальный клиент для OpenAI-совместимых API. OpenAI — алиас для ChatGPT.

from neogram import ChatGPT, OpenAI

client = ChatGPT(
    url="https://api.openai.com/v1",
    headers={"Authorization": "Bearer sk-..."},
    impersonate="chrome")

# OpenAI — то же самое
client = OpenAI(
    url="https://api.openai.com/v1",
    headers={"Authorization": "Bearer sk-..."})

`init(url: str, headers: dict, impersonate: Optional[str] = None)`

Параметр	Тип	По умолчанию	Описание
`url`	`str`	—	Базовый URL API (например `https://api.openai.com/v1`)
`headers`	`dict`	—	HTTP-заголовки (обычно `Authorization`)
`impersonate`	`Optional[str]`	`None`	TLS-фингерпринт для curl_cffi

Поддерживает контекстный менеджер (with ChatGPT(...) as client:).

`generate_chat_completion(model, messages, temperature, max_tokens, stream, **kwargs) -> dict`

Генерация ответа в чате.

Параметр	Тип	По умолчанию	Описание
`model`	`str`	—	Имя модели
`messages`	`list`	—	Список сообщений
`temperature`	`Optional[float]`	`None`	Температура генерации
`max_tokens`	`Optional[int]`	`None`	Максимальное число токенов
`stream`	`bool`	`False`	Потоковый режим

`generate_image(prompt, n, size, response_format, **kwargs) -> dict`

Генерация изображения.

Параметр	Тип	По умолчанию	Описание
`prompt`	`str`	—	Текстовый промпт
`n`	`int`	`1`	Количество изображений
`size`	`str`	`"1024x1024"`	Размер изображения
`response_format`	`str`	`"url"`	Формат ответа (`"url"` или `"b64_json"`)

`generate_embedding(model, input_data, user, **kwargs) -> dict`

Генерация embedding-вектора.

Параметр	Тип	По умолчанию	Описание
`model`	`str`	—	Имя модели
`input_data`	`Union[str, list]`	—	Входные данные
`user`	`Optional[str]`	`None`	Идентификатор пользователя

`generate_transcription(file, model, language, prompt, response_format, temperature, **kwargs) -> Union[dict, str]`

Транскрипция аудио (Speech-to-Text).

Параметр	Тип	По умолчанию	Описание
`file`	`BinaryIO`	—	Аудиофайл
`model`	`str`	—	Имя модели
`language`	`Optional[str]`	`None`	Язык аудио
`prompt`	`Optional[str]`	`None`	Подсказка для модели
`response_format`	`str`	`"json"`	Формат ответа
`temperature`	`float`	`0`	Температура

`generate_translation(file, model, prompt, response_format, temperature, **kwargs) -> Union[dict, str]`

Перевод аудио на английский.

Параметр	Тип	По умолчанию	Описание
`file`	`BinaryIO`	—	Аудиофайл
`model`	`str`	—	Имя модели
`prompt`	`Optional[str]`	`None`	Подсказка для модели
`response_format`	`str`	`"json"`	Формат ответа
`temperature`	`float`	`0`	Температура

`get_models() -> dict`

Получение списка доступных моделей.

Быстрый старт

Telegram бот (синхронный)

from neogram import Bot

bot = Bot(token="YOUR_BOT_TOKEN")

@bot.message_handler(commands=["start"])
def on_start(message):
    bot.send_message(chat_id=message.chat.id, text="Привет!")

@bot.message_handler(content_types=["text"])
def on_text(message):
    bot.send_message(chat_id=message.chat.id, text=f"Вы написали: {message.text}")

bot.infinity_polling()

Telegram бот (асинхронный)

import asyncio
from neogram import AsyncBot

bot = AsyncBot(token="YOUR_BOT_TOKEN")

@bot.message_handler(commands=["start"])
async def on_start(message):
    await bot.send_message(chat_id=message.chat.id, text="Привет!")

async def main():
    async with bot:
        await bot.infinity_polling()

asyncio.run(main())

AI-генерация текста

from neogram import OnlySQ

ai = OnlySQ(key="your-onlysq-key")
answer = ai.generate_answer(
    model="gpt-5.2-chat",
    messages=[{"role": "user", "content": "Расскажи о Python"}]
)
print(answer)

Qwen чат

from neogram import Qwen

qwen = Qwen()
result = qwen.chat(
    model="qwen3.6-plus",
    messages=[{"role": "user", "content": "Привет!"}]
)
print(result)

Перевод и утилиты

from neogram import Deef

deef = Deef()

# Перевод
translated = deef.translate("Hello world", lang="ru")

# Сокращение ссылки
short = deef.short_url("https://example.com/very/long/url")

# Фоновая задача
thread = deef.run_in_bg(some_function, arg1, arg2)

OpenAI-совместимый API

from neogram import ChatGPT

client = ChatGPT(
    url="https://api.openai.com/v1",
    headers={"Authorization": "Bearer sk-..."}
)

response = client.generate_chat_completion(
    model="gpt-5,5",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response["choices"][0]["message"]["content"])

Версия API

Telegram Bot API: 10.0 (константа API_VERSION)
Поддерживаются все типы и методы, включая новые возможности: бизнес-подключения, управляемые боты, подарки, уникальные подарки, чек-листы, платные медиа, live photo, direct messages, guest queries и другие

Логирование

Модуль использует стандартный logging.getLogger("neogram"). Настройте уровень логирования для получения отладочной информации:

import logging
logging.basicConfig(level=logging.DEBUG)

Лицензия

Этот проект распространяется под лицензией MIT. Подробности см. в файле LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
neogram		neogram
LICENSE		LICENSE
README.md		README.md
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation