README.md

---
title: Telegram File Streamer
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---

# 🚀 Telegram Multi-Part File Streamer

A high-performance file upload and streaming service that uses Telegram as a backend storage system. Capable of handling files up to **1TB** with zero-disk buffering.

## ✨ Features

- **🎯 Zero-Disk Buffering**: Direct streaming from HTTP to Telegram
- **📦 Auto-Splitting**: Automatically splits large files into 2GB parts
- **⚡ Multi-Session Load Balancing**: Maximum bandwidth with session rotation
- **📡 Range Request Support**: HTTP 206 for seeking in large files
- **🔄 Parallel Downloads**: IDM and multi-threaded downloader compatible
- **💾 Low Memory**: Optimized for <512MB RAM usage

## 🔧 Required Secrets

This Space requires the following environment variables (add in Settings → Repository secrets):

| Variable | Description | Example |
|----------|-------------|---------|
| `API_ID` | Telegram API ID | `12345678` |
| `API_HASH` | Telegram API Hash | `abc123def456...` |
| `BOT_TOKEN` | Bot Token from @BotFather | `1234567890:ABC...` |
| `MONGO_URI` | MongoDB connection string | `mongodb+srv://...` |
| `SESSION_STRINGS` | Session strings (optional) | `BQAB...,BQAC...` |

### How to Get Credentials:

**Telegram API (API_ID & API_HASH):**
1. Visit https://my.telegram.org/apps
2. Login and create application
3. Copy api_id and api_hash

**Bot Token:**
1. Search @BotFather on Telegram
2. Send `/newbot` command
3. Copy bot token

**MongoDB:**
- Free: MongoDB Atlas (https://www.mongodb.com/cloud/atlas)
- Create cluster → Get connection string

## 📡 API Endpoints

### Upload File
```bash
POST /upload?filename=myfile.zip

curl -X POST "https://YOUR-SPACE.hf.space/upload?filename=file.zip" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@file.zip"
```

### Download File
```bash
GET /dl/{unique_id}

curl "https://YOUR-SPACE.hf.space/dl/{unique_id}" -o output.zip
```

### Get File Info
```bash
GET /info/{unique_id}
```

### Health Check
```bash
GET /health

curl "https://YOUR-SPACE.hf.space/health"
```

## 📊 Performance

| Metric | Value |
|--------|-------|
| Max File Size | 1TB+ |
| Upload Speed | 10-15 MB/s per session |
| Download Speed | 50-100 MB/s |
| RAM Usage | <512MB constant |

## ⚠️ Important

- Ensure Telegram TOS compliance
- Files stored in your Telegram account
- Add multiple SESSION_STRINGS for better performance
- MongoDB IP whitelist: 0.0.0.0/0

## 🐛 Troubleshooting

**Build Failed:**
- Check all secrets are set correctly
- Verify MongoDB URI is valid

**FloodWait Errors:**
- Add more SESSION_STRINGS
- Use user sessions instead of bot only

**Out of Memory:**
- Upgrade Space hardware in Settings

## 📄 License

MIT License

---

**Made with ❤️ for the community**

*Disclaimer: Use responsibly and comply with Telegram's Terms of Service.*