Terabox API & Telegram Bot Documentation

Learn how to integrate Terabox API into your Telegram bot to handle files up to 2GB with our comprehensive guide and ready-to-use code snippets.

API Endpoints

GET /api?url=TERABOX_URL

POST / (with JSON body)

GET /proxy?url=...&file_name=...

API Status Check

GET / (root endpoint)

{
  "success": "✅ Terabox API working...",
  "version": "✨v2.0"
}

API Parameters

Parameter	Type	Description	Example
file_name	String	Name of the file	"movie.mp4"
file_size	String	Human-readable file size	"1.45 GB"
size_bytes	Integer	File size in bytes	1556928461
thumbnail	String	URL of the file thumbnail	"https://example.com/thumb.jpg"
proxy_url	String	Downloadable URL for direct access	"https://api.com/proxy?url=..."
download_link	String	Original direct download link	"https://terabox.com/file.mp4"

API Usage Tips

Display Thumbnail

if file_info.get('thumbnail'):
    context.bot.send_photo(
        chat_id=update.effective_chat.id,
        photo=file_info['thumbnail']
    )

Handle Files Up to 2GB

# Telegram supports files up to 2GB via direct URL
context.bot.send_document(
    chat_id=update.effective_chat.id,
    document=file_info['proxy_url'],
    filename=file_info['file_name'],
    caption=f"📁 {file_info['file_name']}\n📦 Size: {file_info['file_size']}"
)

Show Download Progress

# Show progress during download
response = requests.get(file_info['proxy_url'], stream=True)
total_size = int(response.headers.get('content-length', 0))

with open(file_info['file_name'], 'wb') as f:
    downloaded = 0
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)
        downloaded += len(chunk)
        progress = int(50 * downloaded / total_size)
        update_progress_message(
            f"⬇️ Downloading: [{progress * '='}>{(50-progress) * ' '}] "
            f"{downloaded/total_size:.0%}"
        )

Error Handling

try:
    # API call
except requests.exceptions.RequestException as e:
    update.message.reply_text(f"🌐 Network error: {str(e)}")
except ValueError as e:
    update.message.reply_text(f"🔤 JSON parsing error: {str(e)}")
except Exception as e:
    update.message.reply_text(f"❌ Error: {str(e)}")

Complete Telegram Bot Code

This bot supports files up to 2GB using Terabox API:

import requests
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Updater, CommandHandler, MessageHandler, Filters, CallbackContext

# API Configuration
API_BASE = "https://noor-terabox-api.woodmirror.workers.dev"

def start(update: Update, context: CallbackContext):
    """Send welcome message when user sends /start"""
    update.message.reply_text(
        "🚀 *Terabox Downloader Bot*\n"
        "Send me any Terabox link to download files up to 2GB!\n\n"
        "✅ Supports videos, documents, and archives\n"
        "⚡ Fast and reliable downloads",
        parse_mode="Markdown"
    )

def handle_message(update: Update, context: CallbackContext):
    """Process Terabox links sent by users"""
    # Get the link from user message
    terabox_url = update.message.text.strip()
    
    # Validate the URL
    if "terabox" not in terabox_url:
        update.message.reply_text("⚠️ Please send a valid Terabox link")
        return
    
    # Show processing message
    processing_msg = update.message.reply_text("🔍 Processing your link...")
    
    try:
        # Call Terabox API
        api_url = f"{API_BASE}/api?url={terabox_url}"
        response = requests.get(api_url, timeout=15)
        response.raise_for_status()
        data = response.json()
        
        # Check for API errors
        if "error" in data:
            raise Exception(data["error"])
        
        # Prepare file information
        file_info = {
            "name": data["file_name"],
            "size": data["file_size"],
            "size_bytes": data["size_bytes"],
            "thumbnail": data["thumbnail"],
            "download_url": data["proxy_url"]
        }
        
        # Send thumbnail if available
        if file_info["thumbnail"]:
            context.bot.send_photo(
                chat_id=update.effective_chat.id,
                photo=file_info["thumbnail"],
                caption=f"📸 Preview of *{file_info['name']}*",
                parse_mode="Markdown"
            )
        
        # Send file using direct URL (supports up to 2GB)
        context.bot.send_document(
            chat_id=update.effective_chat.id,
            document=file_info["download_url"],
            filename=file_info["name"],
            caption=f"📁 *{file_info['name']}*\n📦 Size: `{file_info['size']}`",
            parse_mode="Markdown"
        )
        
        # Delete processing message
        processing_msg.delete()
            
    except Exception as e:
        # Handle errors
        processing_msg.edit_text(f"❌ Error: {str(e)}")

def main():
    """Start the Telegram bot"""
    # Replace with your bot token
    TOKEN = "YOUR_TELEGRAM_BOT_TOKEN"
    
    # Create bot instance
    updater = Updater(TOKEN)
    dp = updater.dispatcher
    
    # Register handlers
    dp.add_handler(CommandHandler("start", start))
    dp.add_handler(MessageHandler(Filters.text & ~Filters.command, handle_message))
    
    # Start the bot
    updater.start_polling()
    print("Bot is running...")
    updater.idle()

if __name__ == "__main__":
    main()

Deployment Instructions

Create a new Telegram bot using BotFather
Replace YOUR_TELEGRAM_BOT_TOKEN with your actual token
Set API_BASE to your Terabox API worker URL
Install required packages: pip install python-telegram-bot requests
Run the bot: python your_bot_file.py

Click to copy all code examples to clipboard