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.

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

🖥️ Supported Platforms

📜 Changelog

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.