youtube_helper.api module

YouTube Helper — FastAPI HTTP surface.

Exposes every public function in youtube_helper.main, youtube_helper.streaming and youtube_helper.branding as an HTTP endpoint so youtube-helper can be dropped behind any reverse proxy and consumed by other services. Kept intentionally minimal:

Read endpoints (/metadata, /valid, /resolve, /list-streams, /pick-stream, /channel-info, /channel-videos, /engagement, /engagement-batch, /comments, /ytdlp-version) accept a JSON body or query params and return JSON.
Download endpoints (/video, /audio, /thumbnail) stream the resulting file back to the caller and clean the temp folder as a background task, so no leftover bytes on disk after a request.
/subtitles bundles the downloaded .vtt files into a ZIP.

Install the extra to get the runtime dependencies:

pip install 'youtube-helper[api]'

Then run the app with any ASGI server:

uvicorn youtube_helper.api:app --host 0.0.0.0 --port 8000

Usage Example

>>> # Start the server:
>>> #   uvicorn youtube_helper.api:app --reload
>>> # Get metadata for a URL:
>>> #   curl -X POST -H 'Content-Type: application/json' \
>>> #        -d '{"url":"https://www.youtube.com/watch?v=YE7VzlLtp-4"}' \
>>> #        http://localhost:8000/metadata
>>> # Download the audio:
>>> #   curl -X POST -H 'Content-Type: application/json' \
>>> #        -d '{"url":"https://www.youtube.com/watch?v=YE7VzlLtp-4"}' \
>>> #        -o out.mp3 http://localhost:8000/audio
>>> # Full OpenAPI docs at http://localhost:8000/docs

Author

Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/

class youtube_helper.api.ChannelVideosBody(*, url, max_videos=200, include_shorts=True, include_lives=False, verbose=False)[source]

Bases: BaseModel

Request body for /channel-videos.

Parameters:

url (str)
max_videos (int)
include_shorts (bool)
include_lives (bool)
verbose (bool)

include_lives: bool

include_shorts: bool

max_videos: int

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: str

verbose: bool

class youtube_helper.api.CommentsBody(*, url, max_count=100, cookies_from_browser=None, verbose=False)[source]

Bases: BaseModel

Request body for /comments.

Parameters:

url (str)
max_count (int)
cookies_from_browser (str | None)
verbose (bool)

cookies_from_browser: str | None

max_count: int

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: str

verbose: bool

class youtube_helper.api.DownloadBody(*, url, sample_rate=44100)[source]

Bases: BaseModel

Request body for the download endpoints (video / audio / thumbnail).

Parameters:

url (str)
sample_rate (int)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

sample_rate: int

url: str

class youtube_helper.api.EngagementBatchBody(*, urls, verbose=False)[source]

Bases: BaseModel

Request body for /engagement-batch.

Parameters:

urls (list[str])
verbose (bool)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

urls: list[str]

verbose: bool

class youtube_helper.api.ResolveBody(*, url, prefer='audio', live='auto')[source]

Bases: BaseModel

Request body for the /resolve endpoint.

Parameters:

url (str)
prefer (str)
live (str)

live: str

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

prefer: str

url: str

class youtube_helper.api.StreamFiltersBody(*, url, prefer_codec=None, prefer_format=None, max_fps=None, language=None, include_video_only=True, include_combined=True, cookies_from_browser=None, verbose=False)[source]

Bases: BaseModel

Shared body for /list-streams and /pick-stream (constraint filters).

Parameters:

url (str)
prefer_codec (str | None)
prefer_format (str | None)
max_fps (float | None)
language (str | None)
include_video_only (bool)
include_combined (bool)
cookies_from_browser (str | None)
verbose (bool)

cookies_from_browser: str | None

include_combined: bool

include_video_only: bool

language: str | None

max_fps: float | None

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

prefer_codec: str | None

prefer_format: str | None

url: str

verbose: bool

class youtube_helper.api.SubtitlesBody(*, url, langs=<factory>, auto_only=True, verbose=False)[source]

Bases: BaseModel

Request body for /subtitles.

Parameters:

url (str)
langs (list[str])
auto_only (bool)
verbose (bool)

auto_only: bool

langs: list[str]

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: str

verbose: bool

class youtube_helper.api.UrlBody(*, url, verbose=False)[source]

Bases: BaseModel

Single-URL request body — used by most read endpoints.

Parameters:

url (str)
verbose (bool)

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

url: str

verbose: bool

class youtube_helper.api.YtDlpVersionBody(*, min_version=None)[source]

Bases: BaseModel

Request body for /ytdlp-version.

Parameters:: min_version (str | None)

min_version: str | None

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

youtube_helper.api.audio_endpoint(body, background)

Download the audio track only and stream the file back.

Parameters:

body (DownloadBody)
background (fastapi.BackgroundTasks)

Return type:

fastapi.responses.FileResponse

youtube_helper.api.channel_info_endpoint(body)

Channel-level snapshot (subs, total views, video count).

Parameters:: body (UrlBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.channel_videos_endpoint(body)

List channel videos with normalised engagement metadata.

Parameters:: body (ChannelVideosBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.comments_endpoint(body)

Fetch top comments for a video.

Parameters:: body (CommentsBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.engagement_batch_endpoint(body)

Multi-URL engagement snapshot (tolerant of dead entries).

Parameters:: body (EngagementBatchBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.engagement_endpoint(body)

Single-video engagement snapshot.

Parameters:: body (UrlBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.gui()

Serve the self-contained single-page ‘download bench’ GUI.

The page (defined in youtube_helper.gui) is a build-step-free HTML + Tailwind-CDN + vanilla-JS client that POSTs to the very same /audio / /video endpoints defined below. It adds no server-side logic — it is purely a friendlier front door to the API.

Returns:: The complete HTML document (status 200, text/html).
Return type:: HTMLResponse

youtube_helper.api.health()

Simple liveness probe — no dependency check, just proves the app is up.

Return type:: dict

youtube_helper.api.list_streams(body)

List every video format yt-dlp finds for a URL.

Parameters:: body (StreamFiltersBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.metadata(body)

Return yt-dlp metadata for the given video URL.

Parameters:: body (UrlBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.pick_stream(body)

Pick one best video stream matching the constraints.

Parameters:: body (StreamFiltersBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.resolve(body)

Resolve a URL to a direct ffmpeg-ready media URL.

Parameters:: body (ResolveBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.root()

Redirect the bare root to the GUI so opening the server just works.

Return type:: fastapi.responses.RedirectResponse

youtube_helper.api.subtitles_endpoint(body, background)

Download subtitles (auto or manual); response is a ZIP with the .vtt files.

Parameters:

body (SubtitlesBody)
background (fastapi.BackgroundTasks)

Return type:

fastapi.responses.StreamingResponse

youtube_helper.api.thumbnail_endpoint(body, background)

Download the video’s thumbnail and stream the file back.

Parameters:

body (DownloadBody)
background (fastapi.BackgroundTasks)

Return type:

fastapi.responses.FileResponse

youtube_helper.api.valid(body)

Return whether a URL is a valid video URL for yt-dlp.

Parameters:: body (UrlBody)
Return type:: fastapi.responses.JSONResponse

youtube_helper.api.video_endpoint(body, background)

Download the video (best video + audio) and stream the file back.

Parameters:

body (DownloadBody)
background (fastapi.BackgroundTasks)

Return type:

fastapi.responses.FileResponse

youtube_helper.api.ytdlp_version_endpoint(body)

Return installed yt-dlp version; warn if stale.

Parameters:: body (YtDlpVersionBody)
Return type:: fastapi.responses.JSONResponse