xHamster API

📦 Installation

Install from PyPI using pip:

pip install unofficial-api-for-xhamster

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

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

🚀 Quick Start

Every operation in this wrapper is asynchronous. Run your code inside an async main function:

import asyncio
from xhamster_api import Client
from base_api import DownloadConfigHLS

async def main():
    client = Client()

    # Fetch video metadata
    video = await client.get_video("https://xhamster.com/videos/example-video-123")
    print(video.title)
    print(video.uploader_name)

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

asyncio.run(main())

⚙️ Configuration

Networking configurations (proxies, timeouts, limits) are defined via RuntimeConfig inside the BaseCore wrapper.

Please refer to the shared eaf_base_api Documentation for the complete reference.

from base_api import BaseCore
from base_api.modules.config import RuntimeConfig
from xhamster_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

The entry point for retrieving all resources from xHamster.

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

client = Client()
client_custom = Client(core=BaseCore(RuntimeConfig()))

Constructor Parameters

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

Methods

🎬 Video

dataclass Inherits from BaseMedia. Represents a standard video with metadata extracted from page source JSON elements.

Attributes

Methods

📱 Short

dataclass Inherits from BaseMedia. Represents a mobile-style short-form video.

Attributes

Methods

👤 Pornstar / Creator / Channel

Profiles representing models, creator users, and publisher studios share a common metadata hierarchy.

Attributes

Methods

🔒 Account

Provides authenticated scraper operations inside logged-in sessions.

Methods

⬇️ Downloading Options

xHamster serves videos and shorts via HLS streaming. Configure downloads using DownloadConfigHLS:

from base_api import DownloadConfigHLS

config = DownloadConfigHLS(
    quality="best",            # "best", "half", "worst", or height int (e.g. 720)
    path="./downloads",        # Output directory
    no_title=False,            # Auto-appends title + ".mp4" if False
    return_report=True
)

report = await video.download(configuration=config)

For additional downloading properties, see eaf_base_api Documentation.

📊 Scraping Results

Iterators accept one IteratorConfig policy and yield immutable ScrapeResult[Video] or ScrapeResult[Short] 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 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(
    "reality", 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 xhamster_api.modules.errors. Calls that load media expose ordinary loader failures through base_api.MediaLoadError (or MediaLoadErrors for several sources); inspect original_error/errors. Operations outside media loading, such as login, 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.

LoginFailed now derives from the shared ScraperException; its existing provider import and msg attribute remain available.

See Logging & Cleanup for application logging setup.

from xhamster_api.modules.errors import NotFound, LoginFailed

try:
    account = await client.login(username, password)
except LoginFailed:
    print("Login failed. Please verify credentials.")

💻 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.

xHamster API includes a command-line interface accessible via xhamster_api or python -m xhamster_api:

# Download a single video
xhamster_api --download "https://xhamster.com/videos/sample-title-12345" --quality best --output ./downloads --no-title False

# Or invoke via python -m
python -m xhamster_api --download "https://xhamster.com/videos/sample-title-12345" --quality best --output ./downloads --no-title False

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

CLI Options

🖥️ Supported Platforms

📝 Changelog