YouPorn API

📦 Installation

Install from PyPI using pip:

pip install unofficial-api-for-youporn

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

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

🚀 Quick Start

Wrap YouPorn API calls inside an asynchronous main function:

import asyncio
from youporn_api import Client
from base_api import DownloadConfigHLS, DownloadConfigRAW

async def main():
    client = Client()

    # Fetch a video profile
    video = await client.get_video("https://www.youporn.com/watch/12345/example-video")
    print(video.title)
    print(video.views)

    # Download video via stream-matching HLS/RAW configurations
    hls_config = DownloadConfigHLS(quality="best", path="./downloads")
    raw_config = DownloadConfigRAW(quality="best", path="./downloads")
    await video.download(configuration=hls_config, backup_configuration=raw_config)

asyncio.run(main())

⚙️ Configuration

Proxy/interface, timeout, request-attempt/delay, bandwidth, cache, and concurrency settings are managed by RuntimeConfig inside the shared BaseCore package.

Please refer to the eaf_base_api Documentation for the complete reference.

from base_api import BaseCore
from base_api.modules.config import RuntimeConfig
from youporn_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 class serving as the core interface wrapper.

from youporn_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

👤 BaseProfile, Channel, Pornstar, & Collection

BaseProfile inherits from BaseMedia and provides the common header properties (name, avatar, banner, and description) shared by both Channel and Pornstar profiles. Scrapers representing publisher channels, custom collections, and pornstar profile pages provide listing iterators via videos().

BaseProfile Attributes

Methods

👤 User

dataclass Inherits from BaseMedia. Represents a registered user account profile page.

Attributes

Methods

⬇️ Downloading Options

YouPorn serves videos as both HLS playlists and raw MP4 direct links. In order to handle both cases securely, provide a backup RAW configuration along with the HLS options:

from base_api import DownloadConfigHLS, DownloadConfigRAW

hls_config = DownloadConfigHLS(
    quality="best",
    path="./downloads",
    no_title=False
)

raw_config = DownloadConfigRAW(
    quality="best",
    path="./downloads",
    no_title=False
)

# Will download via HLS if is_hls=True, or fall back to raw direct file downloader if false
success = await video.download(configuration=hls_config, backup_configuration=raw_config)

For more configurations, see references in eaf_base_api Documentation.

📊 Scraping Results

Concurrent search and profile listing methods accept one IteratorConfig policy and yield immutable ScrapeResult[Video] values. The package default loads html, skips terminal page failures, and resolves its unset retry policies from the active RuntimeConfig.request_* settings. A supplied configuration replaces that default, so preserve the HTML source and page error mode explicitly; the example below deliberately opts into yielding page failures. The Video.pornstars and User.get_collections() generators remain direct object iterators.

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 client.search_videos(
    "milf", pages=2, iterator_config=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 youporn_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. Direct unresolved-field access raises base_api.DataNotLoadedError, while operations outside media loading may 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.

The provider-specific RegionBlocked and legacy youporn_api.modules.errors.DataNotLoadedError now derive from ScraperException. The legacy class is distinct from base_api.DataNotLoadedError, which is raised for unresolved media fields.

See Logging & Cleanup for application logging setup.

from base_api import MediaLoadError
from youporn_api.modules.errors import RegionBlocked

try:
    video = await client.get_video(url)
except MediaLoadError as error:
    if isinstance(error.original_error, RegionBlocked):
        print("This video is blocked in your country! Try a permitted proxy if appropriate.")
    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.

YouPorn API includes a command-line interface accessible via youporn_api or python -m youporn_api:

# Download a single video
youporn_api --download "https://www.youporn.com/watch/1234567/sample-title/" --quality best --output ./downloads --no-title False

# Or invoke via python -m
python -m youporn_api --download "https://www.youporn.com/watch/1234567/sample-title/" --quality best --output ./downloads --no-title False

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

CLI Options

🖥️ Supported Platforms

📝 Changelog