realesrgan-api/QUICKSTART.md

# Quick Start Guide

## 1. Local Development (CPU, ~2 minutes)

```bash
# 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)

```bash
# 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)

```bash
# 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)

```bash
# 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

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

# Get detailed system info (CPU, memory, GPU, 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. GPU Setup (Optional, requires NVIDIA)

```bash
# Build with GPU support
docker compose -f docker-compose.gpu.yml build

# Run with GPU
docker compose -f docker-compose.gpu.yml up -d

# Verify GPU is accessible
docker compose -f docker-compose.gpu.yml exec api nvidia-smi

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

## 7. Production Deployment

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

## Troubleshooting

### Models failing to load?

```bash
# 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?

```bash
# 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"?

```bash
# 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](./README.md)
- 🏗️ [Architecture Guide](./CLAUDE.md)
- 🔧 [API Documentation](http://localhost:8000/docs)