unofficial-api-for-xfreehd 1.5

An asynchronous Python API wrapper and scraper for xfreehd.com

XFreeHD API

An asynchronous Python API wrapper and scraper for xfreehd.com

Disclaimer

[!IMPORTANT] This is an unofficial and unaffiliated project. Please read the full disclaimer before use: DISCLAIMER.md

By using this project you agree to comply with the target site's rules, copyright/licensing requirements, and applicable laws. Do not use it to bypass access controls or scrape at disruptive rates.

---

Features

Category	Details
Video Fetching	Fetch video objects with metadata scraped directly from HTML
Video Downloading	RAW/direct-based downloading with quality selection
Album Scraper	Fetch album details and scrape/download images page-by-page or all at once
Video Search	Search videos by query with support for pagination
Async-First	Fully asynchronous (async / await) built on top of asyncio
Built-in Caching	Automatic response caching with configurable limits to reduce redundant network requests
Type Safety	Comprehensive type hinting and dataclass-based models throughout

Networking Features

The networking layer is provided by the eaf_base_api package and is fully configurable through RuntimeConfig:

Feature	Description
HTTP/1.1, HTTP/2, HTTP/3	Configurable HTTP version (v1, v2, v3 — defaults to HTTP/3)
Browser Impersonation	Built-in browser fingerprint impersonation via curl_cffi (defaults to Chrome)
Custom JA3 Fingerprint	Override the TLS fingerprint with a custom JA3 string for advanced use cases
Proxy Support	All proxy types supported (HTTP, HTTPS, SOCKS4, SOCKS5)
Proxy Authentication	Username/password authentication for proxies
Bandwidth Limiting	Set a maximum download speed in MB/s (e.g., 2.0, 3.5)
DNS over HTTPS	Route DNS queries over HTTPS for privacy and bypassing DNS-level blocks
SSL Verification	Toggle SSL certificate verification on or off
Request Delay	Configurable delay between requests to respect rate limits
Concurrency Control	Tune video and page concurrency independently for optimal throughput

---

Supported Platforms

This API has been tested and confirmed working on:

• Windows 11 (x64)
• macOS Sequoia (x86_64)
• Linux (Arch) (x86_64)
• Android 16 (aarch64)

---

Installation

[!WARNING] The installation from Git is temporary. The package will be migrated to PyPI within the next week.

pip install git+https://github.com/EchterAlsFake/unofficial-api-for-xfreehd git+https://github.com/EchterAlsFake/eaf_base_api

---

Quickstart

Have a look at the Documentation for more details

import asyncio
from xfreehd_api import Client, DownloadConfigRAW

async def main():
    # Initialize a Client object
    client = Client()
    
    # Fetch a video
    video_object = await client.get_video("<insert_url_here>")
    
    # Information from Video objects
    print(video_object.title)

    # Download the video
    config = DownloadConfigRAW(quality="best", path="./") # More options in the documentation
    await video_object.download(config)

if __name__ == "__main__":
    asyncio.run(main())

---

Changelog

See Changelog for more details.

---

Support the Project ❤️

I develop all my projects entirely for free because I enjoy it and want to keep them accessible. If you find my work useful, please consider supporting me with a small donation — even 1 € makes a big difference and keeps me motivated!

☕ Ko-fi

https://ko-fi.com/EchterAlsFake

💳 PayPal

https://paypal.me/EchterAlsFake

🪙 Crypto (350+ currencies supported)

---

Contribution

Do you see any issues or having some feature requests? Simply open an Issue or talk in the discussions.

Pull requests are also welcome.

License

Licensed under the LGPLv3 License
Copyright (C) 2023–2026 Johannes Habel