realesrgan-api/API_USAGE.md

API Usage Guide

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

Table of Contents

1. Authentication
2. Upscaling
3. Async Jobs
4. Model Management
5. Health & Monitoring
6. Error Handling
7. Rate Limiting
8. 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:

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:

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

Example:

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:

{
  "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:

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:

{
  "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:

# 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:

# 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:

{
  "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:

# 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:

{
  "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:

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:

{
  "models": ["RealESRGAN_x4plus", "RealESRGAN_x4plus_anime_6B"],
  "provider": "huggingface"
}

Response:

{
  "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:

# 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:

{
  "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:

{
  "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:

{
  "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:

{
  "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,
  "gpu_available": true,
  "gpu_memory_mb": 8192,
  "gpu_memory_used_mb": 2048,
  "execution_providers": ["cuda"],
  "models_dir_size_mb": 268.4,
  "jobs_queue_length": 3
}

Statistics

GET /api/v1/stats

API usage statistics.

Response:

{
  "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:

{
  "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:

{
  "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

{
  "detail": "Model not available: RealESRGAN_x4plus. Download it first."
}

→ Solution: Download model via /api/v1/models/download

File Too Large

{
  "detail": "Upload file exceeds maximum size: 500 MB"
}

→ Solution: Use batch/async jobs or smaller images

Job Not Found

{
  "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

#!/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

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

#!/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