XVideos API

📦 Installation

Install from PyPI using pip:

pip install unofficial-api-for-xvideos

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

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

🚀 Quick Start

Every method in this API is asynchronous. You need to run your code inside an async function:

import asyncio
from xvideos_api import Client

async def main():
    client = Client()

    # Fetch a video
    video = await client.get_video("https://www.xvideos.com/video...")

    # Access metadata
    print(video.title)
    print(video.views)
    print(video.likes)

    # Download the video
    from xvideos_api import DownloadConfigHLS
    config = DownloadConfigHLS(quality="best", path="./downloads")
    await video.download(configuration=config)

asyncio.run(main())

⚙️ Configuration

The API uses eaf_base_api ≥ 4.0.0. Pass a custom BaseCore to configure its singular proxy, bounded request attempts, timeouts, and other networking behavior.

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 xvideos_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

The Client class is your entry point for all interactions. It manages the session and provides methods to fetch videos, search, and access channels/pornstars.

Methods

🎬 Video

dataclass Inherits from BaseMedia. Represents a single video with all its metadata.

Attributes

Methods

📺 Channel

dataclass Inherits from BaseChannelPornstar → BaseMedia. Represents a channel profile.

Attributes

Methods

⭐ Pornstar

dataclass Inherits from BaseChannelPornstar. Represents a performer profile. Has all Channel attributes plus:

Methods

🔑 Account

Provides access to authenticated endpoints. Requires login cookies.

# Provide cookies from your browser session
my_cookies = {
    "session_token": "<your_token>",
    "session_token_auth": "<your_auth_token>",
}

account = client.get_account(cookies=my_cookies)

# Get your liked videos
async for result in account.get_liked_videos(pages=3):
    if result.succeeded:
        print(result.unwrap().title)

These authenticated listing endpoints make the required page requests with POST internally. Callers pass only the public IteratorConfig controls and should not set private request-method fields.

Methods

🔍 Search & Filtering

Use the client.search() method with the sorting enums for powerful filtering:

from xvideos_api.modules.sorting import Sort, SortDate, SortVideoTime, SortQuality

async for result in client.search(
    query="example search",
    sorting_sort=Sort.Sort_rating,
    sorting_date=SortDate.Sort_month,
    sorting_time=SortVideoTime.Sort_long,
    sort_quality=SortQuality.Sort_1080_plus,
    pages=5,
):
    if result.succeeded:
        video = result.unwrap()
        print(f"{video.title}")

Sorting Enums

Sort (Relevance)

SortDate (Time Period)

SortVideoTime (Duration)

SortQuality (Resolution)

⬇️ Downloading

All downloads are configured using the DownloadConfigHLS dataclass:

from xvideos_api import DownloadConfigHLS

config = DownloadConfigHLS(
    quality="best",           # "best", "half", "worst", or int like 720
    path="./downloads",       # Output directory (title auto-appended)
    no_title=False,           # If True, use path as exact filename
    remux=True,               # Convert TS segments to MP4 (needs av)
    return_report=True,       # Return DownloadReport instead of bool
)

report = await video.download(configuration=config)
print(report.status)       # "completed", "failed", or "cancelled"
print(report.downloaded)    # Segments downloaded
print(report.total)         # Total segments

DownloadConfigHLS — Full Options

📄 Pagination & Iterators

Methods like search(), get_playlist(), and channel.videos() return async generators that yield typed ScrapeResult[Video] values. Use succeeded to branch safely or unwrap() to return the item and raise its terminal error on failure:

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

ScrapeResult

IteratorConfig, bounded retries, and custom handlers

All iterator-only controls now live in one IteratorConfig. XVideos' 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, ResultOrder, 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,
    order=ResultOrder.ORIGINAL,
    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(
    "query", pages=3, iterator_config=iterator_config
):
    if result.succeeded:
        print(result.unwrap().title)
    else:
        print(result.stage, result.error)

Authenticated account iterators also accept iterator_config; their required POST request is selected internally, so do not configure private transport fields.

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

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

See Logging & Cleanup for application logging setup.

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

try:
    video = await client.get_video(url)
except MediaLoadError as error:
    if isinstance(error.original_error, NotFound):
        print("Video does not exist")
    elif isinstance(error.original_error, BotDetection):
        print("Bot protection triggered — try a proxy")
    else:
        raise

📝 Changelog

2.5 — 2026-09-15

• 23dec61 / bb96133 / d03b382 — Adopted shared request and download error handling from base_api.modules.provider (requiring eaf-base-api>=4.2.0). Failed downloads now raise DownloadFailed with complete diagnostic context. Modernized HTML scraping for Video, Channel, and Pornstar classes with layout anchors and resilient fallback selectors (JSON-LD, setVideoTitle, setThumbUrl, setVideoHLS, data-id, model links). Added comprehensive unit test suites for channel, pornstar, and video extraction.

2.5 — 2026-08-11

• c1e34b3 / f8ebcb3 — Added generic ScrapeResult[Video] typing and the PEP 561 py.typed marker, left iterator retry policies unset so they resolve from RuntimeConfig, and released 2.5.

2.4 — 2026-08-08

• 9a88d09 — Consolidated account, profile, search, and playlist iterator concurrency, ordering, source loading, retry, and error controls into IteratorConfig; authenticated account listings use their required POST transport internally.

2.4 migration — 2026-08-07

• e39c5ec — 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.

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

XVideos API includes a command-line interface accessible via xvideos_api or python -m xvideos_api:

# Download a single video
xvideos_api --download "https://www.xvideos.com/video..." --quality best --output ./video.mp4 --no-title True

# Download from a file of URLs
xvideos_api --file urls.txt --quality 720 --output ./downloads/ --no-title False

CLI Options

🖥️ Supported Platforms