File Converter API

REST API for converting files between formats with async processing, job tracking, and real-time WebSocket status updates.

What does it do?

• Converts 20+ file formats with 60+ conversion paths
• Images: PNG, JPG, WEBP, BMP, GIF, TIFF, ICO with resize and quality options
• Documents: CSV, TSV, JSON, XML, YAML, TOML, XLSX, Markdown, HTML
• PDF text extraction
• Async processing with ThreadPoolExecutor and real-time WebSocket updates
• Job tracking with SQLite (pending → processing → completed/failed)
• Rate limiting, CORS configuration, API key authentication
• Path traversal protection and input validation
• Automatic job cleanup (24h expiry)

Installation

Requires Python 3.11+

pip install -r requirements.txt

Quick Start

python src/api.py

API starts at http://localhost:8000. Swagger docs at http://localhost:8000/docs.

Usage

Convert a file

curl -X POST "http://localhost:8000/convert?target_format=jpg" \
  -F "file=@photo.png"

{"job_id": "a1b2c3d4e5f6", "status": "pending", "filename": "photo.png", "target_format": "jpg"}

Check job status

curl http://localhost:8000/jobs/a1b2c3d4e5f6

{"id": "a1b2c3d4e5f6", "filename": "photo.png", "source_format": "png", "target_format": "jpg", "status": "completed", "created_at": "2024-01-15T10:30:00+00:00", "completed_at": "2024-01-15T10:30:01+00:00"}

Download result

curl -O http://localhost:8000/jobs/a1b2c3d4e5f6/download

Image conversion with options

curl -X POST "http://localhost:8000/convert?target_format=webp&width=800&quality=90" \
  -F "file=@photo.png"

List supported formats

curl http://localhost:8000/formats

WebSocket real-time status

const ws = new WebSocket("ws://localhost:8000/ws/a1b2c3d4e5f6");
ws.onmessage = (e) => console.log(JSON.parse(e.data));

API Endpoints

Endpoint	Method	Description
/health	GET	Health check
/formats	GET	List supported conversions
/convert	POST	Upload and convert file
/jobs	GET	List recent jobs (filter by status)
/jobs/{job_id}	GET	Job status and details
/jobs/{job_id}/download	GET	Download converted file
/jobs/{job_id}	DELETE	Delete job and files
/ws/{job_id}	WS	Real-time job status

Supported Conversions

Image

PNG ↔ JPG ↔ WEBP ↔ BMP ↔ GIF ↔ TIFF ↔ ICO

Options: width, height (max 10000), quality (1-100)

Document

• CSV ↔ JSON ↔ XML
• CSV ↔ TSV ↔ JSON
• CSV ↔ XLSX
• TSV ↔ XLSX
• JSON ↔ YAML ↔ TOML
• XLSX → JSON / TSV
• Markdown → HTML / TXT
• HTML → TXT

PDF

• PDF → TXT

Configuration

Copy .env.example to .env and adjust:

Variable	Default	Description
API_HOST	0.0.0.0	Server address
API_PORT	8000	Server port
LOG_LEVEL	INFO	Log level
RATE_LIMIT	60/minute	API rate limit
DB_PATH	data/converter.db	SQLite database path
UPLOAD_DIR	uploads	Upload directory
OUTPUT_DIR	outputs	Output directory
MAX_FILE_SIZE	52428800	Max file size (50MB)
API_KEY	(empty)	API key (auth disabled when empty)
MAX_WORKERS	4	Thread pool size
ALLOWED_ORIGINS	*	CORS allowed origins (comma-separated)

Docker

docker-compose -f docker/docker-compose.yml up --build

Tests

pytest tests/ -v

62 tests covering converter, API endpoints, database, and storage.

Project Structure

file-converter-api/
├── Makefile
├── pyproject.toml
├── requirements.txt
├── .env.example
├── README.md
├── src/
│   ├── api.py           # FastAPI endpoints + WebSocket
│   ├── converter.py     # Conversion logic (20+ formats)
│   ├── tasks.py         # ThreadPoolExecutor background tasks
│   ├── storage.py       # File upload/download management
│   ├── database.py      # SQLite job tracking
│   ├── config.py        # Configuration
│   └── logger.py        # Logging
├── docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── tests/
│   ├── conftest.py
│   ├── test_converter.py
│   ├── test_api.py
│   ├── test_database.py
│   └── test_storage.py
├── uploads/
└── outputs/

Technical Details

• API: FastAPI with async file upload, rate limiting (slowapi), CORS, API key auth
• Conversion: Pillow (images), openpyxl (Excel), pdfplumber (PDF), xmltodict (XML), PyYAML, markdown, tomli_w (TOML)
• Async Processing: ThreadPoolExecutor for non-blocking conversions
• Job Tracking: SQLite with status lifecycle and automatic 24h cleanup
• Real-time: WebSocket endpoint for live job status updates
• Storage: UUID-based file naming, automatic cleanup after conversion
• Security: Filename sanitization, path traversal protection, input validation, encoding fallback (UTF-8, Latin-1)
• CI/CD: GitHub Actions automated testing
• Code Quality: black + flake8 + isort + pre-commit hooks
• Container: Docker + docker-compose