ytdlp_simple_api

ytdlp_simple_api — это FastAPI-сервер для скачивания видео и аудио с YouTube и других платформ, поддерживает различные режимы загрузки: лучшее качество, аудио для транскрипции, видео для мессенджеров, полностью ручные настройки, управляет файлами cookie для доступа к контенту, требующему авторизации.

Особенности

Режимы загрузки
- аудио в высоком качестве: Opus, 130 кбит/с.
- аудио для транскрибации через ASR: моно, нормализованное, с передискретизацией.
- видео для чатов: 480p/360p, низкий битрейт, сжатый звук.
- видео в высоком качестве: VP9/AV1, Opus.
- ручная настройка: разрешение, кодеки, битрейт, контейнер.
Управление cookie
- загрузка, просмотр и удаление cookie в формате Netscape для доступа к закрытому контенту.
Управление загрузками
- просмотр списка медиа-файлов, скачивание по прямой ссылке и удаление вручную.
Автоматическая очистка диска
- настраиваемый период хранения файлов, чтобы диск не переполнялся.
Защита API
- аутентификация по Bearer-токену.
Веб-интерфейс
- скачивание медиа-файлов и управление cookie через браузер.

Установка

uv add ytdlp-simple-api

или:

pip install ytdlp-simple-api

Конфигурация

Конфигурация API осуществляется через переменные окружения. Вы можете использовать файл .env для удобства.

Создайте файл .env: Скопируйте .env.example в .env и отредактируйте его:
```
cp .env.example .env
```
Запустите приложение:
```
uvicorn ytdlp_simple_api.api:app --host 0.0.0.0 --port 7860
```
Или используйте скрипт из __init__.py:
```
python -m ytdlp_simple_api
```

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

Переменная	Описание	Значение по умолчанию
`PORT`	порт, на котором будет слушать API	`7860`
`WEB_UI`	`True` для включения веб-интерфейса для загрузки и управления файлами cookie в браузере. `False` для отключения.	`False`
`HIDE_HOME`	`True` для маскировки главной страницы (`/`) UI. Полезно для развертывания на HuggingFace Spaces, где главная страница может быть заменена другим контентом. Если `True`, `/` вернет JSON с информацией о состоянии, иначе - фрейм с внешним URL.	`False`
`API_TOKEN`	Bearer-токен для аутентификации. Если не задан, аутентификация отключена (открытый доступ). Настоятельно рекомендуется установить в производственной среде.	`None`
`DOWNLOADS_DIR`	директория для сохранения загруженных файлов. Если не указано, будет использоваться директория по умолчанию, управляемая библиотекой `ytdlp_simple`.	`None` (автоматически)
`COOKIES_FOLDER`	директория для хранения файлов `cookies.txt`. Если не указано, будет использоваться директория по умолчанию, управляемая библиотекой `ytdlp_simple`.	`None` (автоматически)
`FILE_RETENTION_H`	время в часах, в течение которого файлы будут храниться перед автоматической очисткой. Установите `0` для отключения автоматической очистки. Настоятельно рекомендуется установить значение больше `0` в производственной среде для предотвращения переполнения диска.	`0`

Пример файла .env:

PORT=8000
WEB_UI=True
HIDE_HOME=False
API_TOKEN=your_super_secret_token_here
DOWNLOADS_DIR=/app/downloads
COOKIES_FOLDER=/app/cookies
FILE_RETENTION_H=3

Использование API

Документация по API доступна по адресу /docs (Swagger UI) и /redoc (Redoc UI) после запуска сервера.

Аутентификация

Если переменная окружения API_TOKEN установлена, все эндпоинты, кроме UI, будут требовать аутентификации.

Для аутентификации включите заголовок Authorization в ваших запросах:

Authorization: Bearer your_super_secret_token_here

Если API_TOKEN не установлен, аутентификация отключена, и все эндпоинты доступны без токена.

Эндпоинты загрузки

Все эндпоинты загрузки возвращают DownloadResponse:

{
  "success": true,
  "file_url": "http://localhost:8000/files/video_abc123.mp4",
  "filename": "video_abc123.mp4",
  "error": null,
  "warnings": []
}

В случае ошибки:

{
  "success": false,
  "file_url": null,
  "filename": null,
  "error": "Failed to download video: This video is unavailable.",
  "warnings": ["Some warnings from yt-dlp"]
}

`POST /download/best-audio`

Скачивает аудио в максимально возможном качестве (обычно ~130 кбит/с Opus). Вариант использования: для музыки, подкастов, высококачественного извлечения аудио.

Request Body: BestAudioRequest

{
  "url": "string",
  "prefer_lang": ["ru", "en"], // Optional, предпочтительные языки аудио
  "sponsorblock": true // Optional, удалять рекламные сегменты
}

`POST /download/transcription-audio`

Скачивает и подготавливает аудио для моделей преобразования речи в текст (ASR). Пайплайн: низкий битрейт → нормализация → моно → передискретизация → кодирование. Вариант использования: Whisper, Qwen-3-ASR, Gemma-3n, Microsoft VibeVoice-ASR и т.д.

Request Body: TranscriptionAudioRequest

{
  "url": "string",
  "sample_rate": 16000, // Optional, 16000 или 24000 Гц
  "output_format": "opus", // Optional, "opus", "flac" или "pcm"
  "prefer_lang": null // Optional, предпочтительные языки аудио
}

`POST /download/video-for-chat`

Скачивает видео, оптимизированное для мессенджеров (Telegram/WhatsApp и т.д.). Качество: 480p/360p, минимальный битрейт, самый маленький he-aac аудио, FPS ≤ 30. Корректно обрабатывает вертикальные видео (Shorts, Reels, TikTok).

Request Body: VideoForChatRequest

{
  "url": "string",
  "prefer_lang": null, // Optional
  "sponsorblock": true // Optional
}

`POST /download/best-quality`

Скачивает видео в максимально доступном качестве. Обычно: лучшее видео VP9/AV1 + лучшее аудио Opus. Вариант использования: архивирование, редактирование, просмотр в высоком качестве.

Request Body: BestQualityRequest

{
  "url": "string",
  "prefer_lang": null, // Optional
  "sponsorblock": true, // Optional
  "container": "mp4" // Optional, "mp4", "mkv", "webm", "mov"
}

`POST /download/manual`

Полный контроль над параметрами загрузки. Укажите разрешение, кодеки, битрейт, контейнер и т.д.

Request Body: ManualDownloadRequest

{
  "url": "string",
  "max_resolution": "4k", // Optional, "8k", "4k", "2k", "1080p", "720p", "480p", "360p", "240p", "144p"
  "audio_bitrate": "best", // Optional, "best", "medium", "low"
  "vcodec": "avc", // Optional, "av1", "vp9", "avc", "hevc"
  "acodec": "opus", // Optional, "opus", "aac"
  "speech_lang": "ru", // Optional, "orig", "ru", "en"
  "limit_fps": false, // Optional, ограничить до 30 FPS
  "container": "mp4", // Optional, "mp4", "mkv", "webm", "mov"
  "sponsorblock": true // Optional
}

Эндпоинты файлов

`GET /files`

Получает список всех загруженных файлов с их метаданными.

Response: list[FileInfo]

[
  {
    "filename": "video_123.mp4",
    "size_bytes": 1024000,
    "size_human": "1.0 MB",
    "created_at": "2023-10-27T10:00:00Z",
    "download_url": "/files/video_123.mp4"
  }
]

`GET /files/{filename}`

Скачивает ранее созданный файл по его имени. Файлы автоматически удаляются после периода хранения.

Path Parameter: filename (string)
Response: FileResponse (поток файла)

`DELETE /files/{filename}`

Вручную удаляет загруженный файл.

Path Parameter: filename (string)

Response:

{
  "status": "deleted",
  "filename": "video_123.mp4"
}

Эндпоинты файлов Cookie

`GET /cookies`

Получает список всех загруженных файлов cookie с их метаданными.

Response: list[CookieFileInfo]

[
  {
    "filename": "youtube_cookies.txt",
    "size_bytes": 1500,
    "size_human": "1.5 KB",
    "modified_at": "2023-10-27T10:00:00Z",
    "is_valid": true,
    "domains": ["YouTube", "Google"]
  }
]

`POST /cookies`

Загружает файл cookie в формате Netscape.

Request Body: multipart/form-data
- file: (тип File) Файл cookies.txt в формате Netscape.

Response:

{
  "status": "uploaded",
  "filename": "my_cookies.txt",
  "size": "500 B",
  "domain_hint": ["YouTube"]
}

`POST /cookies/text`

Создает файл cookie путем вставки текстового содержимого.

Request Body: CookieTextRequest

{
  "filename": "my_pasted_cookies.txt",
  "content": "# Netscape HTTP Cookie File..." // Содержимое файла cookie
}

Response:

{
  "status": "created",
  "filename": "my_pasted_cookies.txt",
  "size": "500 B",
  "domains": ["YouTube"]
}

`GET /cookies/{filename}`

Получает информацию о конкретном файле cookie.

Path Parameter: filename (string)
Response: CookieFileInfo

`DELETE /cookies/{filename}`

Удаляет файл cookie.

Path Parameter: filename (string)

Response:

{
  "status": "deleted",
  "filename": "my_cookies.txt"
}

Системные эндпоинты

`GET /`

Проверка состояния сервиса и информация о конфигурации. Если HIDE_HOME установлен в True, возвращает JSON. Если WEB_UI включен, и HIDE_HOME - False, возвращает HTML-страницу с фреймом.

Response (JSON, если HIDE_HOME=True):

{
  "status": "ok",
  "service": "ytdlp-simple-api",
  "config": {
    "downloads_dir": "/tmp/ytdlp_downloads",
    "cookies_configured": true,
    "file_retention_hours": 24
  }
}

`POST /cleanup`

Вручную запускает очистку просроченных файлов.

Response:

{
  "status": "completed",
  "deleted_files": 5,
  "retention_hours": 24
}

Веб-интерфейс (UI)

Если WEB_UI установлен в True, доступны два веб-интерфейса:

UI загрузки

Доступен по адресу /ui или /ui/.

Предоставляет простую форму для загрузки видео/аудио и отображает список загруженных файлов.

UI управления Cookie

Доступен по адресу /cookies-ui или /cookies-ui/.

Позволяет просматривать, загружать (через файл или текст) и удалять файлы cookie в формате Netscape.

Примечание: Если API_TOKEN установлен, в UI появится поле для ввода токена для аутентификации. Если токен не установлен, поле аутентификации будет скрыто.

Предупреждения и особенности

Управление файлами

Временные файлы: все загруженные файлы считаются временными если переменная окружения FILE_RETENTION_H установлена больше 0. Настоятельно рекомендуется настроить FILE_RETENTION_H для автоматической очистки, чтобы избежать переполнения диска.

Безопасность

API Token: если API разворачивается на публичном сервере, обязательно нужно установить API_TOKEN для защиты эндпоинтов от несанкционированного доступа.
Валидация имен файлов: API включает базовую валидацию имен файлов для предотвращения атак типа Path Traversal.
Файлы Cookie: загружайте файлы cookie только не из основных и важных аккаунтов YouTube, X.com, и т.д., поскольку эти аккаунты могут быть заблокированы из-за злоупотреблений! Так же, любой кто сможет прочитать файлы cookies с сервера - сможет получить доступ к аккаунтам. Используйте cookies если с IP сервера невозможно скачивать контент из-за ограничений, либо если требуется обходить возрастные 18+ ограничения сервисов или получать доступ к закрытому контенту. Важно: даже с кукисами собранными с youtube.com скачивание может падать с ошибкой Sign in to confirm you’re not a bot, это проблема в IP, чтобы обойти проверку на бота, нужно собрать кукисы с: google.com, myaccount.google.com и youtube.com как написано здесь, и объединить их в один файл (!).

Производительность

Фоновые задачи: очистка файлов запускается как фоновая задача при каждом запросе загрузки, чтобы не блокировать основной поток.
Конкурентные загрузки: FastAPI может обрабатывать несколько запросов одновременно, и сами загрузки yt-dlp выполняются в асинхронном контексте, но чрезмерное количество одновременных загрузок может повлиять на производительность.

Логирование

API использует стандартный Python-логгер. Вы можете настроить его уровень детализации в вашей среде. Сообщения о создании папок для cookie, UI-ссылки и предупреждения о FILE_RETENTION_H будут отображаться в консоли при запуске.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
src/ytdlp_simple_api		src/ytdlp_simple_api
.env.example		.env.example
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

ytdlp_simple_api

Оглавление

Особенности

Установка

Конфигурация

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

Использование API

Аутентификация

Эндпоинты загрузки

POST /download/best-audio

POST /download/transcription-audio

POST /download/video-for-chat

POST /download/best-quality

POST /download/manual

Эндпоинты файлов

GET /files

GET /files/{filename}

DELETE /files/{filename}

Эндпоинты файлов Cookie

GET /cookies

POST /cookies

POST /cookies/text

GET /cookies/{filename}

DELETE /cookies/{filename}

Системные эндпоинты

GET /

POST /cleanup

Веб-интерфейс (UI)

UI загрузки

UI управления Cookie

Предупреждения и особенности

Управление файлами

Безопасность

Производительность

Логирование

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`POST /download/best-audio`

`POST /download/transcription-audio`

`POST /download/video-for-chat`

`POST /download/best-quality`

`POST /download/manual`

`GET /files`

`GET /files/{filename}`

`DELETE /files/{filename}`

`GET /cookies`

`POST /cookies`

`POST /cookies/text`

`GET /cookies/{filename}`

`DELETE /cookies/{filename}`

`GET /`

`POST /cleanup`

Packages