Redtube API

📦 Installation

Install from PyPI using pip:

pip install unofficial-api-for-redtube

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

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

🚀 Quick Start

Every scraper operation is asynchronous. Wrap calls in a running event loop:

import asyncio
from redtube_api import Client
from base_api import DownloadConfigHLS

async def main():
    client = Client()

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

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

asyncio.run(main())

⚙️ Configuration

Redtube API uses eaf_base_api ≥ 4.0.0. Its singular proxy, request attempts, timeouts, and other networking behavior are configured through 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 redtube_api import Client

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

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

🔌 Client

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

from redtube_api import Client
from base_api import BaseCore

client = Client()
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 JavaScript parameters embedded in the page.

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 metadata hierarchies (UserHelper).

Attributes

Methods

📺 Channel

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

Attributes

Methods

⬇️ Downloading Options

Redtube serves video files via HLS streaming. Configure stream downloading parameters via the DownloadConfigHLS class:

from base_api import DownloadConfigHLS

config = DownloadConfigHLS(
    quality="best",            # "best", "half", "worst", or height int (e.g. 720)
    path="./downloads",        # Destination path
    no_title=False,            # If False, automatically appends title + ".mp4"
)

success = await video.download(configuration=config)

For more configurations regarding downloading setups, please refer to the shared eaf_base_api Documentation.

📊 Scraping Results

Iterator methods yield a typed ScrapeResult[T] wrapper. Use succeeded to branch safely or unwrap() to return the item and raise its terminal error on failure:

async for result in client.search("beach", pages=2):
    if result.succeeded:
        video = result.unwrap()
        print(video.title)
    else:
        print(result.stage, result.url, result.error)

ScrapeResult Attributes

IteratorConfig, bounded retries, and custom handlers

All iterator-only controls now live in one IteratorConfig. Redtube's package default uses ErrorMode.SKIP for terminal page failures; a supplied config replaces that behavior, and a bare IteratorConfig instead defaults to ErrorMode.YIELD. A retry policy's max_attempts includes the initial attempt, so this example makes at most three stage attempts per failed page or item. Each stage attempt may itself perform the request retries configured on BaseCore. Fully populated results require the html source.

Leave page_retry or item_retry as None to derive that stage's bounded policy from the active RuntimeConfig request-attempt and backoff settings; an explicit RetryPolicy overrides it per stage.

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

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

retry = RetryPolicy(
    max_attempts=3, base_delay=0.5, multiplier=2.0,
    max_delay=4.0, jitter=0.2
)
iterator_config = IteratorConfig(
    max_page_concurrency=2,
    max_item_concurrency=8,
    max_pending_items=16,
    load_specific_sources=("html",),
    page_retry=retry,
    item_retry=retry,
    page_error_handler=handle_scrape_error,
    item_error_handler=handle_scrape_error,
)

async for result in client.search(
    "beach", pages=2, iterator_config=iterator_config
):
    if result.succeeded:
        print(result.unwrap().title)
    else:
        print(result.stage, result.error)

ScrapeErrorContext supplies stage, url, error, attempt, max_attempts, page_index, and item_index. A handler returns ErrorAction.RETRY, RAISE, YIELD, or SKIP.

⚠️ Error Handling

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

📝 Changelog

1.4 — 2026-08-11

• 8fcf5ec — Added generic ScrapeResult typing and the PEP 561 py.typed marker, left iterator retry policies unset so they resolve from RuntimeConfig, and released 1.4.

1.3 — 2026-08-08

• eb45470 — Consolidated playlist, user, channel, and search iterator concurrency, ordering, source loading, retry, and error controls into IteratorConfig.

1.3 migration — 2026-08-07

• 46fc0fd — Migrated to the eaf_base_api v4 request and scraping model: fetch_text()/request(), structured exceptions, source-aware media loading, typed scrape streams/results, and bounded retries.

🖥️ Supported Platforms