Beeg API

📦 Installation

Install from PyPI using pip:

pip install unofficial-api-for-beeg

For TS→MP4 remuxing support (recommended for HLS downloads), install with the optional av dependency:

pip install unofficial-api-for-beeg[av]

🚀 Quick Start

Every method in this API is asynchronous. You need to run your code inside an async function:

import asyncio
from beeg_api import Client

async def main():
    client = Client()

    # Fetch a video
    video = await client.get_video("https://beeg.com/1234567")

    # Access metadata
    print(video.title)
    print(video.duration)

    # Download the video
    from base_api import DownloadConfigHLS
    config = DownloadConfigHLS(quality="best", path="./downloads")
    await video.download(configuration=config)

asyncio.run(main())

⚙️ Configuration

The entire API relies on eaf_base_api for its networking. You can configure global settings (proxies, timeouts, etc.) via a custom BaseCore passed into the Client.

Please refer to the eaf_base_api Documentation for the complete reference on how to set up RuntimeConfig and properly integrate it with this API.

from base_api import BaseCore
from base_api.modules.config import RuntimeConfig
from beeg_api import Client

my_config = RuntimeConfig()
my_config.proxy = "socks5://127.0.0.1:9050"
my_config.request_attempts = 4

core = BaseCore(configuration=my_config)
client = Client(core=core)

🔌 Client

The Client class is the entry point for all API requests. It initializes and manages the networking core to request video information pages.

from beeg_api import Client
from base_api import BaseCore

client = Client()

# Or initialize with custom core config
client_custom = Client(core=BaseCore())

Constructor Parameters

• core BaseCore — Networking core instance (default: BaseCore())

Methods

🎬 Video

dataclass Inherits from BaseMedia. Represents a single video with details extracted from Beeg's store facts API.

Attributes

Methods

⬇️ Downloading Options

Beeg video downloads are HLS-only. Configure stream downloads via DownloadConfigHLS:

from base_api import DownloadConfigHLS

config = DownloadConfigHLS(
    quality="best",            # "best", "half", "worst", or height int
    path="./downloads",        # Destination path
    no_title=False,            # If False, automatically appends title + ".mp4"
    return_report=True         # Return a DownloadReport instead of bool
)

report = await video.download(configuration=config)

For full details on download options and setup configurations, see the eaf_base_api Documentation.

⚠️ Error Handling

Source loaders translate request failures into exceptions from beeg_api.modules.errors. Calls that load media expose ordinary loader failures through base_api.MediaLoadError (or MediaLoadErrors for several sources); inspect original_error/errors as shown. Operations outside media loading may still raise package or core exceptions directly.

Request and download failures are logged with the operation, target URL, and full original traceback. Translated exceptions retain the original error in __cause__. Download preparation failures (including metadata loading, quality selection, and output path setup) are also wrapped in DownloadFailed; inspect its cause when diagnosing a failure. The specific availability exceptions listed below remain supported. An explicit DownloadCancelled or asyncio.CancelledError propagates without being wrapped in DownloadFailed. Base downloader False and DownloadReport results remain supported; inspect the result as well as handling exceptions.

The common provider errors NotFound, NetworkError, BotDetection, ProxyError, UnknownNetworkError, and DownloadFailed are catchable through base_api.modules.errors. They derive from ScraperException, which now derives from BaseScraperError. Existing provider import paths remain valid.

See Logging & Cleanup for application logging setup.

from base_api import MediaLoadError
from beeg_api.modules.errors import NotFound

try:
    video = await client.get_video(url)
except MediaLoadError as error:
    if isinstance(error.original_error, NotFound):
        print("This video was not found on Beeg!")
    else:
        raise

💻 CLI Usage

The CLI entry point configures console logging at INFO level. Caught per-URL failures include the URL and full traceback; the default log format shows the logger, file, line, and function. Library applications should configure logging once at startup.

Beeg API includes a command-line interface accessible via beeg_api or python -m beeg_api:

# Download a single video
beeg_api --download "https://beeg.com/1234567" --quality best --output ./downloads --no-title False

# Or invoke via python -m
python -m beeg_api --download "https://beeg.com/1234567" --quality best --output ./downloads --no-title False

# Download from a line-separated file of URLs
beeg_api --file urls.txt --quality best --output ./downloads --no-title False

CLI Options

🖥️ Supported Platforms

📜 Changelog

1.7 — September 15, 2026

• 6bd391b / c5a4549 / 05837ac — Adopted shared request and download error handling from base_api.modules.provider (requiring eaf-base-api>=4.2.0). Failed downloads now raise DownloadFailed with complete context. Added CLI support with automatic console logging, exception chaining, and contextual logging.

1.7 — August 11, 2026

• 9eb18ac — Added complete public type hints and the py.typed marker, updated package metadata for 1.7, and reverted the temporary exact-suffix ID parsing change. The current implementation again uses strip("-0").

Changes during August 7–10, 2026

• 3f3f68d (August 7) — Migrated to eaf_base_api 4: explicit request methods, source-aware media_field("api") loaders, strict loader results, and removal of the v3 compatibility code.
• 2c0a098 (August 9) — Temporarily changed Beeg ID parsing to remove only the exact "-0" suffix.
• 41d4443 (August 10) — Merged that temporary ID parsing change; it was subsequently reverted by 9eb18ac.