realesrgan-api/QUICKSTART.md

Quick Start Guide

1. Local Development (~2 minutes)

# Clone or navigate to project
cd /home/valknar/projects/realesrgan-api

# Build Docker image
docker compose build

# Start API service
docker compose up -d

# Verify running
curl http://localhost:8000/api/v1/health
# Response: {"status":"ok","version":"1.0.0","uptime_seconds":...}

2. Download Models (2-5 minutes)

# List available models
curl http://localhost:8000/api/v1/models

# Download default 4x model (required first)
curl -X POST http://localhost:8000/api/v1/models/download \
  -H 'Content-Type: application/json' \
  -d '{"models": ["RealESRGAN_x4plus"]}'

# Optional: Download anime model
curl -X POST http://localhost:8000/api/v1/models/download \
  -H 'Content-Type: application/json' \
  -d '{"models": ["RealESRGAN_x4plus_anime_6B"]}'

# Verify models downloaded
curl http://localhost:8000/api/v1/models-info

3. Upscale Your First Image

Option A: Synchronous (returns immediately)

# Get a test image or use your own
# For demo, create a small test image:
python3 << 'EOF'
from PIL import Image
import random
img = Image.new('RGB', (256, 256), color=(random.randint(0, 255), random.randint(0, 255), random.randint(0, 255)))
img.save('test-image.jpg')
EOF

# Upscale synchronously (returns output.jpg)
curl -X POST http://localhost:8000/api/v1/upscale \
  -F 'image=@test-image.jpg' \
  -F 'model=RealESRGAN_x4plus' \
  -o output.jpg

echo "Done! Check output.jpg"

Option B: Asynchronous Job (for large images or batches)

# Create upscaling job
JOB_ID=$(curl -s -X POST http://localhost:8000/api/v1/jobs \
  -F 'image=@test-image.jpg' \
  -F 'model=RealESRGAN_x4plus' | jq -r '.job_id')

echo "Job ID: $JOB_ID"

# Check job status (poll every second)
while true; do
  STATUS=$(curl -s http://localhost:8000/api/v1/jobs/$JOB_ID | jq -r '.status')
  echo "Status: $STATUS"
  if [ "$STATUS" != "queued" ] && [ "$STATUS" != "processing" ]; then
    break
  fi
  sleep 1
done

# Download result when complete
curl http://localhost:8000/api/v1/jobs/$JOB_ID/result -o output_async.jpg
echo "Done! Check output_async.jpg"

4. API Documentation

Interactive documentation available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Try endpoints directly in Swagger UI!

5. System Monitoring

# Check system health
curl http://localhost:8000/api/v1/health

# Get detailed system info (CPU, memory, disk, etc.)
curl http://localhost:8000/api/v1/system

# Get API statistics
curl http://localhost:8000/api/v1/stats

# List all jobs
curl http://localhost:8000/api/v1/jobs

6. Production Deployment

# Update docker-compose.prod.yml with your registry/domain
# Edit:
# - Image URL: your-registry.com/realesrgan-api:latest
# - Add domain/reverse proxy config as needed

# Deploy with production compose
docker compose -f docker-compose.prod.yml up -d

# Verify health
curl https://your-domain.com/api/v1/health

Common Operations

Batch Upscale Multiple Images

# Create a batch of images to upscale
for i in {1..5}; do
  python3 << EOF
from PIL import Image
import random
img = Image.new('RGB', (256, 256), color=(random.randint(0, 255), random.randint(0, 255), random.randint(0, 255)))
img.save(f'test_{i}.jpg')
EOF
done

# Submit batch job
curl -X POST http://localhost:8000/api/v1/upscale-batch \
  -F 'images=@test_1.jpg' \
  -F 'images=@test_2.jpg' \
  -F 'images=@test_3.jpg' \
  -F 'images=@test_4.jpg' \
  -F 'images=@test_5.jpg' \
  -F 'model=RealESRGAN_x4plus' | jq '.job_ids[]'

Check Processing Time

# Upscale and capture timing header
curl -i -X POST http://localhost:8000/api/v1/upscale \
  -F 'image=@test-image.jpg' \
  -F 'model=RealESRGAN_x4plus' \
  -o output.jpg 2>&1 | grep X-Processing-Time

List Active Jobs

# Get all jobs
curl http://localhost:8000/api/v1/jobs | jq '.jobs[] | select(.status == "processing")'

# Get only failed jobs
curl http://localhost:8000/api/v1/jobs?status=failed | jq '.'

# Get completed jobs (limited to 10)
curl 'http://localhost:8000/api/v1/jobs?limit=10' | jq '.jobs[] | select(.status == "completed")'

Clean Up Old Jobs

# Remove jobs older than 48 hours
curl -X POST http://localhost:8000/api/v1/cleanup?hours=48

Troubleshooting

Models failing to load?

# Verify models directory
curl http://localhost:8000/api/v1/models-info

# Check container logs
docker compose logs -f api

# Try downloading again
curl -X POST http://localhost:8000/api/v1/models/download \
  -H 'Content-Type: application/json' \
  -d '{"models": ["RealESRGAN_x4plus"]}'

Image upload fails?

# Check max upload size config (default 500MB)
curl http://localhost:8000/api/v1/system

# Ensure image file is readable
ls -lh test-image.jpg

Job stuck in "processing"?

# Check API logs
docker compose logs api | tail -20

# Get job details
curl http://localhost:8000/api/v1/jobs/{job_id}

# System may be slow, check resources
curl http://localhost:8000/api/v1/system

Next Steps

1. ✓ API is running and responding
2. ✓ Models are downloaded
3. ✓ First image upscaled successfully
4. → Explore API documentation at /docs
5. → Configure for your use case
6. → Deploy to production

Support

• 📖 Full README
• 🏗️ Architecture Guide
• 🔧 API Documentation