TeraBox Gateway API

Fast Python gateway for extracting metadata, thumbnails, direct download links, and HLS streaming support from TeraBox share URLs.

!design

This project is available as a PyPI package for direct integration into your Python applications, or it can be run as a standalone API gateway. It provides:

• PyPI Library Integration: Easily import package modules like the client directly in your Python code.

• Interactive Swagger Playground: Access /docs for testing endpoints directly in the browser.

• Web API: Exposes endpoints for listing files and retrieving direct links.

• Unified Cloudflare Worker Proxy: Optimized TeraBox API access handling token resolution.

• Vercel-Ready Deployment: Ready-to-go serverless hosting configuration.

• Flexible Cookie Authentication: Simple string or JSON formatting for upstream auth.

---

Features

• Web API Endpoints:

terabox-gateway/
├── .github/
│   └── workflows/
│       └── publish.yml       # GitHub Actions workflow for PyPI publishing
├── src/
│   └── terabox_gateway/
│       ├── __init__.py        # Package initialization
│       ├── api.py             # Main Flask application and API routes
│       ├── config.py          # Configuration and constants (proxy URLs, headers)
│       ├── terabox_client.py  # TeraBox API client with unified proxy integration
│       ├── utils.py           # Utility functions (validation, formatting)
│       ├── rate_limiter.py    # Per-IP sliding-window rate limiter
│       ├── cache.py           # In-memory LRU cache with TTL expiration
│       ├── main.py            # Package entrypoint for CLI command
│       └── swagger/
│           └── swagger.json   # Swagger OpenAPI JSON specification
├── .env                       # Environment variables (not tracked in git)
├── .env.example               # Example environment configuration
├── pyproject.toml             # PyPI package build configuration
├── requirements.txt           # Python dependencies
├── vercel.json                # Vercel deployment configuration
├── tboxproxy_usage.md         # Unified proxy API documentation
├── main.py                    # Root entry point for running Flask locally or on Vercel
├── .gitignore                 # Git ignore file
├── LICENSE                    # MIT License
└── README.md                  # This file

pip install terabox-gateway

pip install -r requirements.txt

cp .env.example .env

COOKIE_JSON=YdPCtvYteHui3XC6demNk-M2HgRzVrnh0txZQG6X

COOKIE_JSON={"ndus": "YdPCtvYteHui3XC6demNk-M2HgRzVrnh0txZQG6X", "other": "value"}

terabox-gateway

python main.py

curl http://localhost:5000/

curl http://localhost:5000/health

curl http://localhost:5000/swagger.json

curl "http://localhost:5000/api?url=https://1024terabox.com/s/1LNr3tyl5pI5KUM8BecGtyQ"

curl "http://localhost:5000/api?url=https://1024terabox.com/s/1LNr3tyl5pI5KUM8BecGtyQ&resolve=true"

curl "http://localhost:5000/api?mode=resolve&surl=abc123"

curl "http://localhost:5000/api?mode=lookup&surl=abc123"

curl "http://localhost:5000/api?mode=page&surl=abc123"

curl "http://localhost:5000/api?mode=api&jsToken=XYZ&shorturl=abc123"

curl "http://localhost:5000/api?mode=stream&surl=abc123"
Optional: specify quality

curl "http://localhost:5000/api?mode=stream&surl=abc123&type=M3U8_AUTO_720"

curl "http://localhost:5000/api?mode=segment&url=ENCODED_URL"

curl "http://localhost:5000/api?mode=health"

GET /admin/ - Admin Endpoints

• GET /admin/overview: Summary metrics of shares and files

• GET /admin/shares: Search and list resolved shares

• GET /admin/files: Search and filter media files

• GET /admin/kv/entry?surl=...: Lookup raw cached D1 share record

Supported TeraBox Domains

The API validates and supports the following TeraBox domains:

• terabox.app

• teraboxshare.com

• terabox.com

• 1024terabox.com

• teraboxlink.com

• terasharefile.com

• terafileshare.com

• terasharelink.com

---

Integration Examples

You can easily query the gateway API using your preferred programming language. Here are examples of retrieving direct download links for a TeraBox share URL using the /api endpoint:

🐍 Python (using requests)

import requests
def get_direct_links(gateway_url, share_url):
    response = requests.get(
        f"{gateway_url}/api",
        params={"url": share_url}
    )
    if response.status_code == 200:
        data = response.json()
        if data.get("status") == "success":
            for file in data.get("files", []):
                print(f"File: {file['filename']}")
                print(f"Size: {file['size']}")
                print(f"Direct Link: {file['download_link']}\n")
        else:
            print("Error:", data.get("message"))
    else:
        print("HTTP Error:", response.status_code)
Example Usage:

get_direct_links("http://localhost:5000", "https://teraboxshare.com/s/1LNr3tyl5pI5KUM8BecGtyQ")

🟨 JavaScript (Node.js / Browser)

async function getDirectLinks(gatewayUrl, shareUrl) {
    try {
        const response = await fetch(${gatewayUrl}/api?url=${encodeURIComponent(shareUrl)});
        const data = await response.json();
        
        if (response.ok && data.status === 'success') {
            data.files.forEach(file => {
                console.log(File: ${file.filename});
                console.log(Size: ${file.size});
                console.log(Direct Link: ${file.download_link}\n);
            });
        } else {
            console.error('Error:', data.message || 'Failed to resolve links');
        }
    } catch (error) {
        console.error('Fetch Error:', error);
    }
}
// Example Usage:
// getDirectLinks("http://localhost:5000", "https://teraboxshare.com/s/1LNr3tyl5pI5KUM8BecGtyQ");

🐹 Go

package main
import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
)
type FileItem struct {
	Filename     string json:"filename"
	Size         string json:"size"
	DownloadLink string json:"download_link"
}
type APIResponse struct {
	Status string     json:"status"
	Files  []FileItem json:"files"
}
func getDirectLinks(gatewayURL, shareURL string) {
	resp, err := http.Get(fmt.Sprintf("%s/api?url=%s", gatewayURL, url.QueryEscape(shareURL)))
	if err != nil {
		fmt.Println("Error:", err)
		return
	}
	defer resp.Body.Close()
	var result APIResponse
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		fmt.Println("Decode Error:", err)
		return
	}
	if result.Status == "success" {
		for _, file := range result.Files {
			fmt.Printf("File: %s\nSize: %s\nDirect Link: %s\n\n", file.Filename, file.Size, file.DownloadLink)
		}
	} else {
		fmt.Println("API returned an error status")
	}
}
func main() {
	// getDirectLinks("http://localhost:5000", "https://teraboxshare.com/s/1LNr3tyl5pI5KUM8BecGtyQ")
}

---

Environment Variables

You can configure the API using environment variables in your .env file:

| Variable | Description | Default |
|----------|-------------|---------|
| COOKIE_JSON | TeraBox cookies (simple string or JSON) | - |
| TERABOX_COOKIES_JSON | Alternative: JSON string of cookies | - |
| TERABOX_COOKIES_FILE | Alternative: Path to cookies JSON file | - |
| HOST | Server host address | 0.0.0.0 |
| PORT | Server port | 5000 |
| FLASK_DEBUG | Enable Flask debug mode (1 or 0) | 0 |
| RATE_LIMIT | Max requests per window per IP | 30 |
| RATE_WINDOW | Rate limit window size in seconds | 60 |
| CACHE_TTL | Cache entry time-to-live in seconds | 60 |
| CACHE_MAX_SIZE | Maximum number of cached entries | 500 |
| HTTP_MAX_RETRIES | Max retry attempts for transient server/network failures | 3 |
| HTTP_INITIAL_DELAY | Initial delay for the first retry backoff in seconds | 0.5 |
| HTTP_BACKOFF_FACTOR | Multiplier applied to backoff delay per retry | 2.0 |

Cookie Priority:
1. COOKIE_JSON (from .env)
2. TERABOX_COOKIES_JSON
3. TERABOX_COOKIES_FILE

---

Technical Implementation

Unified Proxy Architecture

The TeraBox Gateway uses a unified Cloudflare Worker proxy for all TeraBox API interactions. This architecture provides:

• Reduced Network Overhead: 33-50% fewer HTTP requests (1-2 instead of 2-3 per request)

• Server-Side Token Handling: Automatic jsToken extraction handled by the proxy

• Mode-Based Operations: Three distinct modes for different use cases

Proxy Modes

The unified proxy supports 5 distinct modes, all accessible via the /proxy endpoint:

1. mode=resolve (Recommended)

• Automatically fetches the share page, extracts jsToken, and returns file metadata

• Single HTTP call for most common use cases

• Returns JSON with file list and metadata

• Best for production use

• Returns raw HTML of TeraBox share page

• Useful for debugging and manual token extraction

• Returns HTML content

• Direct API access when jsToken is already known

• Used for directory listings and advanced scenarios

• Returns JSON from TeraBox API

• Fetches M3U8 playlist and rewrites segment URLs

• Requires surl parameter (short URL ID)

• Optional type parameter for quality selection (default: M3U8_AUTO_360)

• Enables HLS video streaming in browsers and players

• Returns modified M3U8 playlist

• Proxies individual video segments (.ts, .m4s files)

• Automatically used by rewritten playlists

• Returns binary media data

Request Flow

Client Request → Flask API → Unified Proxy (mode=resolve) → TeraBox API → Response
               ↓
         (if directory)
               ↓
         Unified Proxy (mode=api) → Directory Contents → Response

Key Benefits:

• ✅ Simplified codebase with no manual token parsing

• ✅ Faster response times due to fewer roundtrips

• ✅ More reliable token extraction (handled server-side)

• ✅ Better error handling and reporting

---

Deployment

Deploy to Vercel

The easiest way to deploy your own instance of the TeraBox Gateway API is to use Vercel.

Click the button below to clone and deploy this repository with one click:

Alternatively, deploy manually using the Vercel CLI:

1. Install Vercel CLI (optional):

   npm i -g vercel
   

2. Deploy:

   vercel
   

3. Set environment variables in Vercel dashboard:
- Go to your project settings
- Add COOKIE_JSON with your ndus token value

The vercel.json configuration is already set up for you.

---

Troubleshooting

Common Issues

Error 400141 - Verification Required

• The link is password-protected

FLASK_DEBUG=1

This project is licensed under the MIT License. See the LICENSE file for details.

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Contact

For questions or support, contact @Saahiyo

---

Acknowledgments

• Built with Flask 3.x (native async) and aiohttp for efficient async operations

• Unified Cloudflare Worker proxy for optimized API access

• Designed for seamless Vercel deployment

• Supports multiple TeraBox domains and share URL formats