Eporner API

📦 Installation

Install from PyPI using pip:

pip install unofficial-api-for-eporner

For custom CLI printing support, install with the optional cli components:

pip install unofficial-api-for-eporner[cli]

🚀 Quick Start

Run your scraping scripts inside an active event loop using async context:

import asyncio
from eporner_api import Client, DownloadConfigRAW
from eporner_api.modules.locals import Encoding

async def main():
    client = Client()

    # Retrieve video info
    video = await client.get_video("https://www.eporner.com/video-12345/example-video")
    print(video.title)
    print(video.views)

    # Download video in best quality using H264 encoding
    config = DownloadConfigRAW(quality="best", path="./downloads")
    await video.download(configuration=config, mode=Encoding.mp4_h264)

asyncio.run(main())

⚙️ Configuration

Adjust timeouts, a proxy or bound interface, request retry/delay settings, cache limits, and iterator concurrency using the shared RuntimeConfig passed into BaseCore.

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 eporner_api import Client

my_config = RuntimeConfig()
my_config.proxy = "socks5://127.0.0.1:9050"
my_config.request_attempts = 4  # Total attempts, including the first request

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

Iterator, retry, and error policy

All listing methods accept one IteratorConfig | None. If omitted, Eporner eagerly loads both "api" and "html", skips terminal page failures, and installs a handler that skips ResourceGone/NotFound failures (including those nested in media-load errors) while retrying other failures within the resolved budget. A supplied config replaces that complete default.

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

async def handle_scrape_error(context: ScrapeErrorContext) -> ErrorAction:
    print(context.stage, context.url, context.attempt, context.error)
    return ErrorAction.RETRY

retry = RetryPolicy(
    max_attempts=3, base_delay=0.5, multiplier=2.0, max_delay=8.0, jitter=0.25
)
iterator_config = IteratorConfig(
    max_page_concurrency=2,
    max_item_concurrency=10,
    load_specific_sources=("api", "html"),
    order=ResultOrder.ORIGINAL,
    page_retry=retry,
    item_retry=retry,
    page_error_mode=ErrorMode.SKIP,
    item_error_mode=ErrorMode.YIELD,
    page_error_handler=handle_scrape_error,
    item_error_handler=handle_scrape_error,
)

max_attempts includes the first attempt. page_error_handler and item_error_handler are routed independently. This example shares one callable because it intentionally applies the same retry decision to both stages; use separate callables when page and item policy differ. A handler may return RETRY, RAISE, YIELD, or SKIP; retrying remains capped, and a final RETRY falls back to the stage's configured ErrorMode.

🔌 Client

Scraper instance to orchestrate requests and retrieve media objects.

from eporner_api import Client
from base_api import BaseCore

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

Constructor Parameters

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

Methods

🎬 Video

dataclass Inherits from BaseMedia. Represents a single video with details extracted from API endpoints and HTML elements. If a video has been deleted or removed by the platform, a ResourceGone error is raised cleanly.

Attributes

Methods

⭐ Pornstar

dataclass Inherits from BaseProfile → BaseMedia. Represents an Eporner model profile with parsed statistics, bio, and video streams.

Attributes

Methods

📺 Channel

dataclass Inherits from BaseProfile → BaseMedia. Represents an Eporner channel profile with rank, stats, logo, banner, and video stream pagination.

Attributes

Methods

⬇️ Downloading Options

Eporner serves direct MP4 media files. Download options are configured via the DownloadConfigRAW class, specifying the encoding type (AV1 or H.264):

from base_api import DownloadConfigRAW
from eporner_api.modules.locals import Encoding

config = DownloadConfigRAW(
    quality="best",            # "best", "half", "worst", or height (e.g. 1080)
    path="./downloads",        # Output directory
    no_title=False,            # Auto-appends title + ".mp4" if False
    allow_multipart=True,      # Enable multi-threaded segmented range downloads
    max_workers=5              # Concurrent segment downloaders
)

# Download using H.264 codec
await video.download(configuration=config, mode=Encoding.mp4_h264)

For more configurations regarding RAW downloaders, please read the reference inside eaf_base_api Documentation.

📊 Scraping Results

Concurrently iterated methods yield immutable ScrapeResult[Video] values. A result contains exactly one of item or error:

async for result in client.search_videos("couple", sorting_gay="0", sorting_order="latest", sorting_low_quality="1", per_page=10):
    if result.succeeded:
        video = result.unwrap()     # Returns Video or raises the typed scrape error
        print(video.title)
    else:
        print(f"{result.stage} error for {result.url}: {result.error}")

ScrapeResult Attributes

📜 Changelog

2.4.1 (current)

• 2026-09-15 · 3ee78ee / 6b80518 / f9fd944 / 01429e8 — Updated dependency to eaf-base-api>=4.2.0 and adopted centralized request/download error handling. Failed downloads now raise DownloadFailed with complete context. Added BaseProfile, Pornstar, and Channel classes with profile video scraping via videos(). Added Client.get_channel(). Expanded Video metadata (dual API/HTML source loading for title, views, embed URL, and thumbnails; length_seconds integer type; clean ResourceGone exception when videos are deleted or removed).
• 2026-08-14 · 7f1bbac — Added HTML-backed tags, categories, and uploader fields; renamed get_available_qualities() to video_qualities(); and made optional pornstar biography fields tolerant of missing page elements.
• 2026-08-11 · c8f2974 — Added typed ScrapeResult[Video] annotations and py.typed; fixed the Eporner v2 API URL/list response handling and treated package NotFound as a terminal resource error. Default iterator error handling now uses the structured ScrapeErrorContext/ErrorAction handler.
• 2026-08-08 · f862f1c — Replaced all per-method concurrency, loading, ordering, retry, and callback arguments with IteratorConfig while preserving eager ("api", "html") loading.
• 2026-08-07 · e3c682a — Migrated to eaf-base-api>=4.0.0: explicit request methods, source-aware media loaders, bounded scheduling, deterministic stream cleanup, structured scrape results, and validated extractors.

📋 Sorting Enums

Search endpoints accept sorting parameters defined inside eporner_api.modules.sorting:

Gay

Order

LowQuality

⚠️ Error Handling

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

from base_api import MediaLoadError
from eporner_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("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.

Eporner API includes a command-line interface accessible via eporner_api or python -m eporner_api:

# Download a single video
eporner_api --download "https://www.eporner.com/video-12345/sample-video/" --quality best --output ./downloads --no-title False

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

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

CLI Options

🖥️ Supported Platforms