VK Music Bot API — гайд по использованию
Привет. Меня зовут Traft, я разработчик, и это статья про мой open-source проект — VK Music Bot API.
Идея проекта простая: сделать удобный backend, который позволяет использовать музыку из ВКонтакте внутри Telegram (в том числе Mini Apps) без костылей, сложной логики и постоянного переписывания одного и того же кода.
Репозиторий: 👉 https://github.com/TraftG/vk-music-bot-api
Какую проблему я решал
Музыка ВК — одна из самых больших библиотек, но:
- официальный клиент не всегда удобен
- в Telegram нет нативного доступа
- большинство ботов — это хрупкие скрипты без архитектуры
Я хотел решение, которое:
- работает как нормальный API
- легко подключается к Telegram
- можно масштабировать и дорабатывать
- не смешивает UI, бота и логику VK в одном файле
Так появился VK Music Bot API.
Что умеет VK Music Bot API
Основной функционал
Поиск музыки
- поиск по названию и исполнителю
- быстрые ответы
- получение метаданных трека
Скачивание MP3
- прямая работа с источниками VK
- нормальное качество
- возможность обработки через FFmpeg
История прослушиваний
- сохранение треков пользователя
- база для рекомендаций
- подготовка к персонализации
Авторизация через Telegram
- без логинов и паролей
- через Telegram WebApp InitData
- нативная и безопасная схема
Проект изначально делался как backend, а не «бот-комбайн».
Технологический стек
Backend
- FastAPI — быстрый async-фреймворк
- Uvicorn — ASGI сервер
- Pydantic — строгая валидация данных
- Motor — асинхронный драйвер MongoDB
Интеграции
- VKPyMusic — работа с VK Audio
- Aiogram — Telegram Bot API
- yt-dlp — загрузка аудио
- FFmpeg — обработка и конвертация
База данных
- MongoDB — пользователи, история, рекомендации
Архитектура проекта
Проект разбит на логические слои и следует принципам чистой архитектуры.
music-bot/ ├── app/ │ ├── core/# конфигурация и БД │ ├── models/# Pydantic-схемы │ ├── routers/# API endpoints │ ├── services/# бизнес-логика │ └── main.py # точка входа
Почему так
- логика отделена от API
- код легко читать и расширять
- удобно тестировать
- новый разработчик быстро вникает
API Endpoints
Аутентификация
POST /api/auth/login
Авторизация через Telegram InitData
POST /api/auth/history
Сохранение трека в историю
Музыка
GET /api/music/search?q=запрос
Поиск треков
GET/api/music/download/{track_id}
Скачивание MP3
GET /api/music/recommendations
Персональные рекомендации
Документация
- Swagger: /docs
- ReDoc: /redoc
Быстрый старт
git clone https://github.com/TraftG/vk-music-bot-api.git cd vk-music-bot-api python3 -m venv venv source venv/bin/activate pip install -r requirements.txt cp .env.example .envdocker run -d -p 27017:27017 mongo uvicorn app.main:app --reload
API будет доступно на http://localhost:8000.
Почему асинхронность
Весь проект построен на async / await:
- высокая пропускная способность
- отсутствие блокировок
- нормальная работа под нагрузкой
Пример lifecycle-логики:
@asynccontextmanagerasyncdeflifespan(app: FastAPI): await connect_to_mongo() yieldawait close_mongo_connection()
Производительность
Средние показатели:
- поиск треков: < 500 ms
- рекомендации: < 200 ms
- авторизация: < 100 ms
Проект масштабируется через workers:
uvicorn app.main:app --workers 4
Deployment
Проект готов к продакшену.
Docker
FROM python:3.11-slim WORKDIR /appCOPY requirements.txt .RUN pip install -r requirements.txtCOPY . .CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
Работает на:
- VPS
- Docker / Kubernetes
- Railway / Render
- AWS / GCP
Open Source и вклад
Проект под лицензией MIT.
Можно:
- использовать
- модифицировать
- встраивать в свои проекты
PR, идеи и issues — приветствуются.
Что дальше
Планы развития:
- плейлисты
- кеширование популярных треков
- улучшение рекомендаций
- WebSocket-обновления
- отдельный Telegram-бот
- аналитика
Заключение
VK Music Bot API — это не «очередной бот», а нормальный backend, который можно использовать как основу для своих проектов.
Если вам нужен:
- Telegram Mini App с музыкой
- музыкальный бот
- API для VK Audio
— этот проект закроет большую часть задач.
Если понравилось — буду рад ⭐ на GitHub.