Thumbzilla API

📦 Installation

Install from PyPI using pip:

pip install unofficial-api-for-thumbzilla

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

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

🚀 Quick Start

import asyncio
from thumbzilla_api import Client
from base_api import DownloadConfigHLS

async def main():
    client = Client()

    # Fetch video metadata
    video = await client.get_video("https://www.thumbzilla.com/watch/12345")
    print(video.title)
    print(video.views)

    # Download video via HLS
    config = DownloadConfigHLS(quality="best", path="./downloads")
    await video.download(configuration=config)

asyncio.run(main())

⚙️ Configuration

Proxy/interface, timeout, request-attempt/delay, cache, and concurrency settings are handled via RuntimeConfig passed to BaseCore.

Please refer to the eaf_base_api Documentation for details.

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

my_config = RuntimeConfig()
my_config.proxy = "socks5://127.0.0.1:9050"
my_config.request_attempts = 4
my_config.videos_concurrency = 8
my_config.pages_concurrency = 2

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

🔌 Client

Main entry point class to execute searches and load resource models.

from thumbzilla_api import Client
client = Client()

Constructor Parameters

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

Methods

🎬 Video

dataclass Inherits from BaseMedia. Represents a single video with metadata extracted from LD+JSON structured data and JavaScript media definitions.

Attributes

Methods

📜 Playlist

dataclass Inherits from BaseMedia. Represents a user-curated playlist.

Attributes

Methods

👤 User / Pornstar / Amateur

Scraper objects representing creators, actors, and registered users share a common base class (UserHelper).

Attributes

Methods

📺 Channel

dataclass Inherits from UserHelper. Represents a publisher studio channel page.

Attributes

Methods

⬇️ Downloading Options

Thumbzilla serves video files via HLS streaming. The scraper auto-constructs a master M3U8 playlist from the JSON media definitions. Configure stream downloading parameters via the DownloadConfigHLS class:

from base_api import DownloadConfigHLS

config = DownloadConfigHLS(
    quality="best",
    path="./downloads",
    no_title=False,
    return_report=True
)

report = await video.download(configuration=config)

For more configurations, see the shared eaf_base_api Documentation.

📊 Scraping Results

A missing main video container raises ValueError instead of returning an empty successful extraction. During iteration, Helper logs the page URL and traceback, then applies the page retry/error policy; a terminal failure is a PageFetchError when raised or yielded. An existing container with no matching videos can still produce an empty result.

All concurrently iterated methods accept one IteratorConfig policy and yield immutable ScrapeResult[Video] values. The package default loads html and skips terminal page failures. A supplied configuration replaces that default, so include load_specific_sources=("html",) and page_error_mode=ErrorMode.SKIP when preserving both behaviors; the example below deliberately opts into yielding page failures.

The public configuration fields are max_page_concurrency, max_item_concurrency, max_pending_items, extract_in_thread, order, both *_error_mode, both *_retry, both *_error_handler, load_specific_fields, and load_specific_sources.

from base_api import ErrorAction, ErrorMode, ResultOrder, RetryPolicy, ScrapeErrorContext
from base_api.modules.config import IteratorConfig

async def handle_error(context: ScrapeErrorContext) -> ErrorAction:
    if context.attempt < context.max_attempts:
        return ErrorAction.RETRY
    return ErrorAction.YIELD

iterator_config = IteratorConfig(
    max_page_concurrency=2,
    max_item_concurrency=8,
    order=ResultOrder.ORIGINAL,
    load_specific_sources=("html",),
    page_retry=RetryPolicy(max_attempts=4, base_delay=0.5, jitter=0.25),
    item_retry=RetryPolicy(max_attempts=4, base_delay=0.5, jitter=0.25),
    page_error_mode=ErrorMode.YIELD,
    item_error_mode=ErrorMode.YIELD,
    page_error_handler=handle_error,
    item_error_handler=handle_error,
)

async for result in pornstar.get_videos(
    pages=3, iterator_configuration=iterator_config
):
    if result.succeeded:
        video = result.unwrap()
        print(video.title)
    else:
        print(result.stage, result.url, result.attempts, result.error)

ScrapeResult Attributes

⚠️ Error Handling

Source loaders translate request failures into exceptions from thumbzilla_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.

A missing main video container raises ValueError instead of returning an empty successful extraction. During iteration, Helper logs the page URL and traceback, then applies the page retry/error policy; a terminal failure is a PageFetchError when raised or yielded. An existing container with no matching videos can still produce an empty result.

from base_api import MediaLoadError
from thumbzilla_api.modules.errors import NotFound, BotDetection

try:
    video = await client.get_video(url)
except MediaLoadError as error:
    if isinstance(error.original_error, NotFound):
        print("This video does not exist!")
    elif isinstance(error.original_error, BotDetection):
        print("Scraper was blocked by anti-bot measures.")
    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.

Thumbzilla API includes a command-line interface accessible via thumbzilla_api or python -m thumbzilla_api:

# Download a single video
thumbzilla_api --download "https://www.thumbzilla.com/video/ph123456789/sample-title" --quality best --output ./downloads --no-title False

# Or invoke via python -m
python -m thumbzilla_api --download "https://www.thumbzilla.com/video/ph123456789/sample-title" --quality best --output ./downloads --no-title False

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

CLI Options

🖥️ Supported Platforms

📝 Changelog