PornHub API

📦 Installation

Install from PyPI using pip:

pip install unofficial-api-for-pornhub

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

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

🚀 Quick Start

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

import asyncio
from pornhub_api import Client

async def main():
    client = Client()

    # Fetch a video
    video = await client.get_video("https://www.pornhub.com/view_video.php?viewkey=...")

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

    # Download the video
    from base_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 for networking. Configure its singular proxy, bounded request attempts, timeouts, and other runtime behavior through a custom BaseCore.

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 pornhub_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, headers, cookies, and authentication — providing methods to fetch individual resources, search, and access account features.

from pornhub_api import Client
from base_api import BaseCore

# Basic initialization
client = Client()

# Construct without logging in
client = Client(
    core=BaseCore(),
    email="user@example.com",
    password="password",
)
await client.login()

# Or await the factory for construction plus completed login
client = await Client.create(
    core=BaseCore(),
    email="user@example.com",
    password="password",
    login=True,
)

Constructor Parameters

• core BaseCore | None — Optional networking core instance. If omitted or None (default), a fresh BaseCore instance is initialized with default headers and cookies.
• email str | None — Account email for login
• password str | None — Account password for login

Methods

🎬 Video

dataclass Inherits from BaseMedia. Represents a single video with metadata from both HTML scraping and the Webmaster API. Supports dual loading modes: API-only (fast) and HTML (full data including m3u8 URLs for downloading).

Attributes

Methods & Properties

⭐ Pornstar

dataclass Inherits from UserHelper → BaseMedia. Represents a pornstar profile. Shared base with Model and User for profile info and video iteration.

Attributes

Methods

👤 Model

dataclass Inherits from UserHelper → BaseMedia. Represents a model profile and inherits get_videos() from UserHelper.

Attributes

Same as Pornstar: url, name, bio, about, info.

Methods

🧑 User

dataclass Inherits from UserHelper → BaseMedia. Represents a regular user profile and inherits get_videos() from UserHelper.

Attributes

Same as Pornstar: url, name, bio, about, info.

Methods

📺 Channel

dataclass Inherits from BaseMedia. Represents a production channel with studio-level metadata.

Attributes

Methods

📋 Playlist

dataclass Inherits from BaseMedia. Represents a video playlist with title, description, tags, and video count. Uses the chunked API endpoint internally for video iteration.

Attributes

Methods

🖼️ Album

dataclass Inherits from BaseMedia. Represents a photo album with rating, views, tags, and individual photo download support.

Attributes

Methods

🎞️ GIF

dataclass Inherits from BaseMedia. Represents a single GIF with voting data, source video link, and a direct download URL.

Attributes

Methods

📱 Short

dataclass Inherits from BaseMedia. Represents a Pornhub short-form video with metadata extracted from inline JSON.

Attributes

Methods

🔐 Account

Represents the authenticated user account. Access via client.account after calling client.login(). Provides methods for recommendations, history, favorites, feed, and subscriptions.

Attributes

from pornhub_api import Client

client = Client(email="user@example.com", password="password")
await client.login()

print(client.account.name)        # Username
print(client.account.is_premium)   # True/False

# Get recommended videos
async for result in client.account.get_recommended():
    if result.succeeded:
        video = result.unwrap()
        await video.load_sources("html")
        print(video.title)

Methods

🔍 Search & Filtering

The PornHub API offers three distinct search methods with rich filtering options:

Video Search Filters

GIF Search Filters

HubTraffic API Filters

# Search professional videos, sorted by most viewed
async for result in client.search_videos(
    query="blonde",
    production_type="professional",
    sort_by="mv",
    pages=3
):
    if result.succeeded:
        video = result.unwrap()
        await video.load_sources("html")
        print(video.title)

# Fast search via HubTraffic API
async for result in client.search_hubtraffic(
    query="amateur",
    sort_by="newest",
    period="weekly"
):
    if result.succeeded:
        video = result.unwrap()
        print(video.title, video.views)

⬇️ Downloading

The PornHub API uses two download modes depending on the content type:

• HLS (DownloadConfigHLS) — For Videos and Shorts. Downloads HLS streams with quality selection, threaded segment downloading, resume support, and optional TS→MP4 remuxing.
• RAW (DownloadConfigRAW) — For GIFs and Album photos. Direct file downloads with multi-threaded range request support.

HLS Download (Videos & Shorts)

from base_api import DownloadConfigHLS

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

# Must have HTML loaded for m3u8 URLs
video = await client.get_video(url, load_html=True)
success = await video.download(configuration=config)

RAW Download (GIFs & Photos)

from base_api import DownloadConfigRAW

config = DownloadConfigRAW(
    quality="best",           # "best", "half", "worst", or height int
    path="./downloads",       # Output directory or file path
    no_title=False,           # Auto-append title + ".mp4" if False
    allow_multipart=True,     # Use multi-threaded range requests
    max_workers=5             # Number of parallel download threads
)

gif = await client.get_gif(url)
success = await gif.download(configuration=config)

For full details on all download configuration options, refer to the eaf_base_api Documentation.

📄 Pagination & Iterators

Methods like search_videos(), pornstar.get_videos(), channel.get_videos(), and the account iterators yield typed ScrapeResult[T] 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_videos("college", pages=2):
    if result.succeeded:
        video = result.unwrap()
        await video.load_sources("html")
        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. Pornhub'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.

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_videos(
    "college", 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

All custom exceptions inherit from PornhubAPIError, which inherits from the shared ScraperException and BaseScraperError. Source loaders translate request failures into these library exceptions. 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, such as login, 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.

Pornhub retains its own exception classes: each common error also subclasses the corresponding shared error. For example, pornhub_api.modules.errors.DownloadFailed can be caught as either PornhubAPIError or base_api.modules.errors.DownloadFailed.

from base_api import MediaLoadError
from pornhub_api.modules.errors import PornhubAPIError, NotFound, BotDetection, LoginFailed

try:
    video = await client.get_video(url, load_html=True, load_api=False)
except MediaLoadError as error:
    if isinstance(error.original_error, NotFound):
        print("Video does not exist")
    elif isinstance(error.original_error, BotDetection):
        print("Bypassing bot protection failed")
    elif isinstance(error.original_error, PornhubAPIError):
        print("PornHub API error occurred")
    else:
        raise

try:
    await client.login()
except LoginFailed as e:
    print(f"Login failed: {e}")

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

The PornHub API package includes a built-in CLI accessible via phub, pornhub_api, or python -m pornhub_api:

# Download a single video
phub --download "https://www.pornhub.com/view_video.php?viewkey=..." --quality best --output ./downloads --no-title False

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

# Download liked videos (requires login)
phub --liked --email user@example.com --password pass --quality best --output ./favorites --no-title False

# Download with video ID as filename and a limit
phub --download "https://www.pornhub.com/view_video.php?viewkey=..." --quality best --output ./downloads --no-title False --id-as-title --limit 10

CLI Options

📝 Changelog

5.4.3 — 2026-09-15

• d3c8743 / 81e4629 / d034cf2 — Adopted centralized request and download error handling from base_api.modules.provider (requiring eaf-base-api>=4.2.0). Failed downloads now raise DownloadFailed with full context. Added dedicated Pornstar class inheriting from UserHelper and client.get_pornstar(). Greatly expanded Short metadata with 15 new attributes (duration, categories, tags, is_verified, like/dislike counts and info, token, author ID/type, external links, preview URLs). Added comprehensive unit test suites covering Short, User, Album, Channel, Gif, Playlist, and Video. Removed redundant code and streamlined scraping logic.

5.4.3 — 2026-09-06

• f8bbe99 — Introduced PornhubAPIError base exception class (inheriting from Exception) for all library errors; converted GifPendingReview and VideoDisabled to inherit from PornhubAPIError instead of BaseException. Removed redundant SubscriptionHelper class. Refactored scrape methods (get_videos, get_uploads, get_gifs, search, and account iterators) to return AsyncGenerator[ScrapeResult, None] directly. Added default pages=1 to Album.get_photos() and removed ProcessPoolExecutor overhead. Fixed Short.get_video() by removing invalid @property decorator from the async method. Updated Video.likes type annotation to int | str | None. Consolidated HLS download handling via _download_hls. Streamlined HTML parsing extractors with Lexbor CSS selectors and URL deduplication. Refactored CLI URL handler dispatch and argument options. Announced native MCP documentation server support.
• 5553a68 / 56578f3 — Removed the wrapper's hard-coded User-Agent from default headers and replaced constructor-triggered background login with the awaited Client.create(..., login=True) factory method, setting default core=None to instantiate independent networking cores.
• 50f41e3 / 8cfac95 — Corrected aspect ratio calculation in estimate_width for HLS variants providing height without width.

5.4.1 — 2026-08-13

• fe1d38f — Added the HTML-backed UserHelper.name field with selectors for both supported profile layouts.

5.4 — 2026-08-11

• 68f6a65 / b16c2ea — Sanitized Short, GIF, and Video download titles to prevent path traversal and illegal filenames, then released 5.4.
• 6a5c064 — Added generic ScrapeStream/ScrapeResult typing and the PEP 561 py.typed marker; iterator retry fields remain unset so they resolve from RuntimeConfig.

5.3.1 fixes — 2026-08-10

• 1acf957 — Made iterator source loading opt-in by default, fixed profile /videos URL construction, separated upload/model/playlist extractors for richer structured results and deduplication, tolerated missing playlist descriptions, and corrected count parsing (issues #96, #97, and #98).

5.3.1 iterator synchronization — 2026-08-08

• 69bffd6 — Consolidated iterator concurrency, ordering, source loading, retry, and error controls into IteratorConfig.

5.3.1 v4 migration — 2026-08-07

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

5.3.1 — 2026-08-06

• f93c3eb — Fixed Video.author(load_html), corrected the CLI entry point, and released the 5.3.1 patch.

🖥️ Supported Platforms