OFFICIAL PYTHON SDK

Build with Redirox

Everything you need to create smart links from Python. Install the lightweight SDK and bring short URLs, passwords, expiration, and QR codes into your workflow.

Get started View source

Getting started

The official Redirox Python SDK lets your scripts and applications create short links and look up existing ones. It uses the public Redirox service by default.

Requirements: Python 3.8 or newer. No API key is required by the SDK.

Installation

Install the package from PyPI:

Terminal

pip install redirox

For the optional Telegram bot example below, install Pyrogram and tgcrypto separately:

Terminal

pip install pyrogram tgcrypto

Quick start

Create a client, shorten a link, and read the URL from the returned dictionary.

Python

from redirox import Redirox

client = Redirox()
result = client.shorten("https://example.com")

print(result["short_url"])

Configuration

By default, the client sends requests to https://redirox.pages.dev with a 15-second request timeout. Pass base_url if you host your own Redirox instance or customize timeout for your network requirements.

Python

from redirox import Redirox

# Custom base URL and timeout (in seconds)
client = Redirox(
    base_url="https://redirox.pages.dev",
    timeout=20
)

Parameter	Type	Default	Description
`base_url`	str	`"https://redirox.pages.dev"`	Base URL for the Redirox API endpoint (trailing slash removed automatically).
`timeout`	int \| float	`15`	Request timeout duration in seconds.

Shorten links

shorten(url, password=None, expires_at=None, generate_qr=False) creates a new link. The URL must start with http:// or https://.

Python

result = client.shorten("https://example.com/a/long/path")
print(result["code"])
print(result["short_url"])

Argument	Type	Purpose
`url`	str	Destination URL (required)
`password`	str \| None	Optional link password
`expires_at`	str \| None	Optional ISO-formatted expiration date and time
`generate_qr`	bool	Include a QR code as a PNG data URL

Password protection

Add a password when creating a link. Visitors must enter it before the destination opens.

Python

result = client.shorten(
    "https://example.com/private",
    password="mypassword"
)
print(result["has_password"])  # True

Expiring links

Pass an ISO-formatted future date and time as expires_at.

Python

from datetime import datetime, timedelta, timezone

expires_at = (datetime.now(timezone.utc) + timedelta(hours=1)).isoformat()
result = client.shorten(
    "https://example.com/limited-time",
    expires_at=expires_at
)
print(result["expires_at"])

Expired links are unavailable. Redirox checks expiration when a visitor opens the link.

QR codes

Set generate_qr=True to receive a base64-encoded PNG data URL in qr_code. It is generated when the link is created, not fetched later by info().

Python

import base64

result = client.shorten("https://github.com", generate_qr=True)
qr_data_url = result["qr_code"]

if qr_data_url:
    image_bytes = base64.b64decode(qr_data_url.split(",", 1)[1])
    with open("qr.png", "wb") as file:
        file.write(image_bytes)

Link information

Use the link’s six-character code to retrieve its destination, visit count, creation date, expiration date, and password status.

Python

info = client.info("abc123")
print(info["url"])
print(info["visits"])
print(info["has_password"])

info(code) returns the JSON response from GET /info/<code>. It does not return the password or QR image.

Verify password

Validate a password against a password-protected link programmatically.

Python

try:
    check = client.verify("abc123", "mypassword")
    print("Destination URL:", check["url"])
except RediroxAuthError:
    print("Invalid password provided!")

Telegram bot example

Use the SDK inside a Pyrogram bot to reply with a short URL. Replace the placeholders with your own Telegram credentials.

Python

from pyrogram import Client, filters
from redirox import Redirox

app = Client(
    "redirox-bot",
    api_id=12345,
    api_hash="YOUR_API_HASH",
    bot_token="YOUR_BOT_TOKEN"
)
redirox = Redirox()

@app.on_message(filters.text & filters.private)
async def shorten_link(_, message):
    try:
        result = redirox.shorten(message.text.strip())
        await message.reply_text(result["short_url"])
    except Exception as error:
        await message.reply_text(f"Could not shorten link: {error}")

app.run()

The SDK uses synchronous HTTP requests. For high-volume async bots, run calls off the event loop.

Responses

shorten() returns a dictionary with the fields below. qr_code is None unless requested; expires_at is None unless supplied.

Python

{
    "code": "abc123",
    "short_url": "https://redirox.pages.dev/abc123",
    "url": "https://example.com",
    "qr_code": None,
    "expires_at": None,
    "has_password": False
}

Error handling

The Redirox SDK provides a dedicated hierarchy of custom exceptions, allowing you to catch specific errors cleanly:

Exception	Status	Description
`RediroxValidationError`	400	Raised when invalid URL or payload parameters are provided.
`RediroxAuthError`	401	Raised when an incorrect password is supplied for a link.
`RediroxNotFoundError`	404	Raised when the requested short link does not exist or has expired.
`RediroxConnectionError`	-	Raised on network failure or unreachable host.
`RediroxAPIError`	5xx	Raised on other unexpected HTTP/API errors.
`RediroxError`	-	Base class for all Redirox SDK exceptions.

Python

from redirox import (
    Redirox,
    RediroxValidationError,
    RediroxAuthError,
    RediroxNotFoundError,
    RediroxConnectionError,
    RediroxAPIError,
)

client = Redirox()

try:
    result = client.shorten("https://example.com")
except RediroxValidationError as e:
    print("Validation failed:", e)
except RediroxAuthError as e:
    print("Authentication error:", e)
except RediroxNotFoundError as e:
    print("Link not found:", e)
except RediroxConnectionError as e:
    print("Connection problem:", e)
except RediroxAPIError as e:
    print(f"API Error ({e.status_code}):", e)

Resources

Explore the package and the open-source project.

PyPI package SDK source Website source