BROKENXAPI 2.0.7

Official async Python SDK and CLI for BrokenX YouTube API

BROKENXAPI Documentation

BROKENXAPI is an async-first Python SDK that allows developers to access BrokenX YouTube services securely using an API key.

[!CAUTION] IMPORTANT DISCLAIMER

This project is designed for Educational Purposes Only. Usage of this software to download copyrighted content (Music/Videos) without permission may violate YouTube's Terms of Service and local copyright laws.

The developer (MR BROKEN) assumes NO responsibility for any misuse or legal consequences resulting from the use of this tool. Use it at your own risk.

---

Features

• Async / non-blocking
• Secure header-based authentication
• Clean SDK (no backend exposure)
• Telegram-powered media delivery

Requirements

• Python 3.8 or higher
• Valid BrokenX API key Get it from Here
• Internet access

---

Install with pip:

pip install BROKENXAPI

Quick Start

Recommended: set your API key as an environment variable for local development.

Linux / macOS:

export API_KEY="BROKENXAPI-XXXX"

Windows (cmd):

set API_KEY=BROKENXAPI-XXXX

Basic usage (using env var):

import os
import asyncio
from brokenxapi import BrokenXAPI

API_KEY = os.getenv("API_KEY")  # recommended
async def main():
    async with BrokenXAPI(api_key=API_KEY) as api:
        result = await api.search("Arijit Singh")
        print(result)

asyncio.run(main())

Or pass API key directly (less secure):

async with BrokenXAPI(api_key="BROKENXAPI-XXXX") as api:
    result = await api.search("No Copyright sounds", video=False)

---

Authentication

BROKENXAPI uses header-based authentication. The SDK sets the Authorization header for you when you pass api_key to the constructor.

Header format (used internally by the SDK):

Authorization: Bearer YOUR_API_KEY

Do not commit or share your API key in public repositories.

---

Context-manager usage:

async with BrokenXAPI(api_key="...") as api:
    ...

search(query: str, video: bool = False, limit: int = 20)

Search for YouTube content.

• Parameters:

  • query (str): search keyword
  • video (bool): False = audio (default), True = video
  • limit (int): number of results to request (default 20)

• Returns: dict — a JSON-compatible dictionary including keys such as:

  • title
  • video_id
  • duration
  • thumbnail

Example:

result = await api.search("no copyright sounds", video=False)
video_id = result["video_id"]

download(video_id: str, media: str = "audio")

Download audio or video via BrokenX backend.

• Parameters:

  • video_id (str): YouTube video id
  • media (str): "audio" (default) or "video"

• Returns: dict — download metadata. Example keys:

  • telegram_url

Example:

audio = await api.download(video_id, media="audio")
print(audio["telegram_url"])

Notes:

• The SDK converts boolean query parameters to strings before sending (e.g. True -> "true").
• All network requests raise on non-2xx responses via aiohttp.

---

Error Handling

All SDK errors inherit from BrokenXAPIError.

Example:

from brokenxapi.exceptions import BrokenXAPIError

try:
    await api.download("invalid_id")
except BrokenXAPIError as e:
    print("Error:", e)

---

CLI

The package provides a brokenx CLI. Example usage:

• Save API key:

brokenx auth BROKENXAPI-XXXX

• Search:

brokenx search "no copyright sounds"

• Download (audio):

brokenx download VIDEO_ID

• Download (video):

brokenx download VIDEO_ID -v

---

Running tests

Set the YTKEY env var before running tests that hit the real backend:

export API_KEY="BROKENXAPI-XXXX"
pytest -q

Tests that require a live API key are skipped automatically if API_KEY is not set.