Initial Real-ESRGAN API project setup
This commit is contained in:
Developer
627
API_USAGE.md
Normal file
627
API_USAGE.md
Normal file
@@ -0,0 +1,627 @@
|
||||
# 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,
|
||||
"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:**
|
||||
```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`
|
||||
Reference in New Issue
Block a user