realesrgan-api/API_USAGE.md

# API Usage Guide

Complete reference for Real-ESRGAN API endpoints and usage patterns.

## Table of Contents

1. [Authentication](#authentication)
2. [Upscaling](#upscaling)
3. [Async Jobs](#async-jobs)
4. [Model Management](#model-management)
5. [Health & Monitoring](#health--monitoring)
6. [Error Handling](#error-handling)
7. [Rate Limiting](#rate-limiting)
8. [Examples](#examples)

---

## Authentication

Currently, the API has no authentication. For production, add authentication via:

- API keys in headers
- OAuth2
- API Gateway authentication (recommended for production)

---

## Upscaling

### Synchronous Upscaling

**POST /api/v1/upscale**

Upload an image and get upscaled result directly.

**Parameters:**
- `image` (file, required): Image file to upscale
- `model` (string, optional): Model name (default: `RealESRGAN_x4plus`)
- `tile_size` (integer, optional): Tile size for processing large images
- `tile_pad` (integer, optional): Padding between tiles
- `outscale` (float, optional): Output scale factor

**Response:**
- On success: Binary image file with HTTP 200
- Header `X-Processing-Time`: Processing time in seconds
- On error: JSON with error details

**Example:**

```bash
curl -X POST http://localhost:8000/api/v1/upscale \
  -F 'image=@input.jpg' \
  -F 'model=RealESRGAN_x4plus' \
  -o output.jpg

# With custom tile size
curl -X POST http://localhost:8000/api/v1/upscale \
  -F 'image=@large_image.jpg' \
  -F 'model=RealESRGAN_x4plus' \
  -F 'tile_size=512' \
  -o output.jpg
```

**Use Cases:**
- Small to medium images (< 4MP)
- Real-time processing
- Simple integrations

### Batch Upscaling

**POST /api/v1/upscale-batch**

Submit multiple images for upscaling via async jobs.

**Parameters:**
- `images` (files, required): Multiple image files (max 100)
- `model` (string, optional): Model name
- `tile_size` (integer, optional): Tile size

**Response:**
```json
{
  "success": true,
  "job_ids": ["uuid-1", "uuid-2", "uuid-3"],
  "total": 3,
  "message": "Batch processing started for 3 images"
}
```

**Example:**

```bash
curl -X POST http://localhost:8000/api/v1/upscale-batch \
  -F 'images=@img1.jpg' \
  -F 'images=@img2.jpg' \
  -F 'images=@img3.jpg' \
  -F 'model=RealESRGAN_x4plus' | jq '.job_ids[]'
```

---

## Async Jobs

### Create Job

**POST /api/v1/jobs**

Create an asynchronous upscaling job.

**Parameters:**
- `image` (file, required): Image file to upscale
- `model` (string, optional): Model name
- `tile_size` (integer, optional): Tile size
- `tile_pad` (integer, optional): Tile padding
- `outscale` (float, optional): Output scale

**Response:**
```json
{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status_url": "/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000",
  "result_url": "/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000/result"
}
```

**Example:**

```bash
curl -X POST http://localhost:8000/api/v1/jobs \
  -F 'image=@large_image.jpg' \
  -F 'model=RealESRGAN_x4plus' \
  -H 'Accept: application/json'
```

### Get Job Status

**GET /api/v1/jobs/{job_id}**

Check the status of an upscaling job.

**Response:**
```json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "model": "RealESRGAN_x4plus",
  "created_at": "2025-02-16T10:30:00",
  "started_at": "2025-02-16T10:30:05",
  "completed_at": null,
  "processing_time_seconds": null,
  "error": null
}
```

**Status Values:**
- `queued`: Waiting in processing queue
- `processing`: Currently being processed
- `completed`: Successfully completed
- `failed`: Processing failed

**Example:**

```bash
# Check status
curl http://localhost:8000/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000

# Poll until complete (bash)
JOB_ID="550e8400-e29b-41d4-a716-446655440000"
while true; do
  STATUS=$(curl -s http://localhost:8000/api/v1/jobs/$JOB_ID | jq -r '.status')
  echo "Status: $STATUS"
  [ "$STATUS" = "completed" ] && break
  sleep 5
done
```

### Download Result

**GET /api/v1/jobs/{job_id}/result**

Download the upscaled image from a completed job.

**Response:**
- On success: Binary image file with HTTP 200
- On failure: JSON error with appropriate status code

**Status Codes:**
- `200 OK`: Result downloaded successfully
- `202 Accepted`: Job still processing
- `404 Not Found`: Job or result not found
- `500 Internal Server Error`: Job failed

**Example:**

```bash
# Download result
curl http://localhost:8000/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000/result \
  -o upscaled.jpg
```

### List Jobs

**GET /api/v1/jobs**

List all jobs with optional filtering.

**Query Parameters:**
- `status` (string, optional): Filter by status (queued, processing, completed, failed)
- `limit` (integer, optional): Maximum jobs to return (default: 100)

**Response:**
```json
{
  "total": 42,
  "returned": 10,
  "jobs": [
    {
      "job_id": "uuid-1",
      "status": "completed",
      "model": "RealESRGAN_x4plus",
      "created_at": "2025-02-16T10:30:00",
      "processing_time_seconds": 45.23
    },
    ...
  ]
}
```

**Example:**

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

# List only completed jobs
curl 'http://localhost:8000/api/v1/jobs?status=completed'

# List first 5 jobs
curl 'http://localhost:8000/api/v1/jobs?limit=5'

# Parse with jq
curl -s http://localhost:8000/api/v1/jobs | jq '.jobs[] | select(.status == "failed")'
```

---

## Model Management

### List Models

**GET /api/v1/models**

List all available models.

**Response:**
```json
{
  "available_models": [
    {
      "name": "RealESRGAN_x2plus",
      "scale": 2,
      "description": "2x upscaling",
      "available": true,
      "size_mb": 66.7,
      "size_bytes": 69927936
    },
    ...
  ],
  "total_models": 4,
  "local_models": 1
}
```

**Example:**

```bash
curl http://localhost:8000/api/v1/models | jq '.available_models[] | {name, scale, available}'
```

### Download Models

**POST /api/v1/models/download**

Download one or more models.

**Request Body:**
```json
{
  "models": ["RealESRGAN_x4plus", "RealESRGAN_x4plus_anime_6B"],
  "provider": "huggingface"
}
```

**Response:**
```json
{
  "success": false,
  "message": "Downloaded 1 model(s)",
  "downloaded": ["RealESRGAN_x4plus"],
  "failed": ["RealESRGAN_x4plus_anime_6B"],
  "errors": {
    "RealESRGAN_x4plus_anime_6B": "Network error: Connection timeout"
  }
}
```

**Example:**

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

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

### Get Model Info

**GET /api/v1/models/{model_name}**

Get information about a specific model.

**Response:**
```json
{
  "name": "RealESRGAN_x4plus",
  "scale": 4,
  "description": "4x upscaling (general purpose)",
  "available": true,
  "size_mb": 101.7,
  "size_bytes": 106704896
}
```

### Models Directory Info

**GET /api/v1/models-info**

Get information about the models directory.

**Response:**
```json
{
  "models_directory": "/data/models",
  "total_size_mb": 268.4,
  "model_count": 2
}
```

---

## Health & Monitoring

### Health Check

**GET /api/v1/health**

Quick API health check.

**Response:**
```json
{
  "status": "ok",
  "version": "1.0.0",
  "uptime_seconds": 3600.5,
  "message": "Real-ESRGAN API is running"
}
```

### Readiness Probe

**GET /api/v1/health/ready**

Kubernetes readiness check (models loaded).

**Response:** `{"ready": true}` or HTTP 503

### Liveness Probe

**GET /api/v1/health/live**

Kubernetes liveness check (service responsive).

**Response:** `{"alive": true}`

### System Information

**GET /api/v1/system**

Detailed system information and resource usage.

**Response:**
```json
{
  "status": "ok",
  "version": "1.0.0",
  "uptime_seconds": 3600.5,
  "cpu_usage_percent": 25.3,
  "memory_usage_percent": 42.1,
  "disk_usage_percent": 15.2,
  "execution_providers": ["cpu"],
  "models_dir_size_mb": 268.4,
  "jobs_queue_length": 3
}
```

### Statistics

**GET /api/v1/stats**

API usage statistics.

**Response:**
```json
{
  "total_requests": 1543,
  "successful_requests": 1535,
  "failed_requests": 8,
  "average_processing_time_seconds": 42.5,
  "total_images_processed": 4200
}
```

### Cleanup

**POST /api/v1/cleanup**

Clean up old job directories.

**Query Parameters:**
- `hours` (integer, optional): Remove jobs older than N hours (default: 24)

**Response:**
```json
{
  "success": true,
  "cleaned_jobs": 5,
  "message": "Cleaned up 5 job directories older than 24 hours"
}
```

---

## Error Handling

### Error Response Format

All errors return JSON with appropriate HTTP status codes:

```json
{
  "detail": "Model not available: RealESRGAN_x4plus. Download it first using /api/v1/models/download"
}
```

### Common Status Codes

| Code | Meaning | Example |
|------|---------|---------|
| 200 | Success | Upscaling completed |
| 202 | Accepted | Job still processing |
| 400 | Bad Request | Invalid parameters |
| 404 | Not Found | Job or model not found |
| 422 | Validation Error | Invalid schema |
| 500 | Server Error | Processing failed |
| 503 | Service Unavailable | Models not loaded |

### Common Errors

**Model Not Available**
```json
{
  "detail": "Model not available: RealESRGAN_x4plus. Download it first."
}
```
→ Solution: Download model via `/api/v1/models/download`

**File Too Large**
```json
{
  "detail": "Upload file exceeds maximum size: 500 MB"
}
```
→ Solution: Use batch/async jobs or smaller images

**Job Not Found**
```json
{
  "detail": "Job not found: invalid-job-id"
}
```
→ Solution: Check job ID, may have been cleaned up

---

## Rate Limiting

Currently no rate limiting. For production, add via:
- API Gateway (recommended)
- Middleware
- Reverse proxy (nginx/traefik)

---

## Examples

### Example 1: Simple Synchronous Upscaling

```bash
#!/bin/bash
set -e

API="http://localhost:8000"

# Ensure model is available
echo "Checking models..."
curl -s "$API/api/v1/models" | jq -e '.available_models[] | select(.name == "RealESRGAN_x4plus" and .available)' > /dev/null || {
  echo "Downloading model..."
  curl -s -X POST "$API/api/v1/models/download" \
    -H 'Content-Type: application/json' \
    -d '{"models": ["RealESRGAN_x4plus"]}' | jq .
}

# Upscale image
echo "Upscaling image..."
curl -X POST "$API/api/v1/upscale" \
  -F 'image=@input.jpg' \
  -F 'model=RealESRGAN_x4plus' \
  -o output.jpg

echo "Done! Output: output.jpg"
```

### Example 2: Async Job with Polling

```python
import httpx
import time
import json
from pathlib import Path

client = httpx.Client(base_url='http://localhost:8000')

# Create job
with open('input.jpg', 'rb') as f:
    response = client.post(
        '/api/v1/jobs',
        files={'image': f},
        data={'model': 'RealESRGAN_x4plus'},
    )
    job_id = response.json()['job_id']
    print(f'Job created: {job_id}')

# Poll status
while True:
    status_response = client.get(f'/api/v1/jobs/{job_id}')
    status = status_response.json()
    print(f'Status: {status["status"]}')
    
    if status['status'] == 'completed':
        break
    elif status['status'] == 'failed':
        print(f'Error: {status["error"]}')
        exit(1)
    
    time.sleep(5)

# Download result
result_response = client.get(f'/api/v1/jobs/{job_id}/result')
Path('output.jpg').write_bytes(result_response.content)
print('Result saved: output.jpg')
```

### Example 3: Batch Processing

```bash
#!/bin/bash
API="http://localhost:8000"

# Create batch from all JPGs in directory
JOB_IDS=$(curl -s -X POST "$API/api/v1/upscale-batch" \
  $(for f in *.jpg; do echo "-F 'images=@$f'"; done) \
  -F 'model=RealESRGAN_x4plus' | jq -r '.job_ids[]')

echo "Jobs: $JOB_IDS"

# Wait for all to complete
for JOB_ID in $JOB_IDS; do
  while true; do
    STATUS=$(curl -s "$API/api/v1/jobs/$JOB_ID" | jq -r '.status')
    [ "$STATUS" = "completed" ] && break
    sleep 5
  done
  
  # Download result
  curl -s "$API/api/v1/jobs/$JOB_ID/result" -o "upscaled_${JOB_ID}.jpg"
  echo "Completed: $JOB_ID"
done
```

---

## Webhooks (Future)

Planned features:
- Job completion webhooks
- Progress notifications
- Custom callbacks

---

## Support

For issues or questions:
1. Check logs: `docker compose logs api`
2. Review health: `curl http://localhost:8000/api/v1/health`
3. Check system info: `curl http://localhost:8000/api/v1/system`