API_DOCUMENTATION.md

# CodeFormer API Documentation

This document describes the programmatic interface for the CodeFormer Face Restoration service.

## Base URL
The API is accessible at:
`https://esmailx50-job.hf.space` (or your specific Hugging Face Space URL)

---

## 1. Process Images
Processes one or more images for face restoration and enhancement.

- **Endpoint:** `/api/process`
- **Method:** `POST`
- **Consumes:** `multipart/form-data` OR `application/json`

### Parameters
| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `fidelity` | float | `0.5` | Fidelity weight ($w$). Range [0, 1]. Lower is more "hallucinated" detail, higher is more identity preservation. |
| `upscale` | int | `2` | Final upscaling factor. Supported: `1`, `2`, `4`. |
| `background_enhance` | bool | `false` | Enhance the background using Real-ESRGAN. |
| `face_upsample` | bool | `false` | Upsample restored faces using Real-ESRGAN. |
| `return_base64` | bool | `false` | If true, includes the processed image as a base64 string in the JSON response. |

### Input Formats

#### A. Multipart Form Data (`multipart/form-data`)
Useful for uploading files directly.
- `image`: One or more image files (as a list).
- Other parameters as form fields.

**Example (curl):**
```bash
curl -X POST 
  -F "image=@my_photo.jpg" 
  -F "fidelity=0.7" 
  -F "background_enhance=true" 
  https://esmailx50-job.hf.space/api/process
```

#### B. JSON (`application/json`)
Useful for sending base64-encoded image data.
- `image_base64`: A single base64 string (with or without data URI prefix).
- `images_base64`: (Optional) A list of base64 strings for batch processing.
- Other parameters as JSON keys.

**Example (curl):**
```bash
curl -X POST 
  -H "Content-Type: application/json" 
  -d '{
    "image_base64": "data:image/png;base64,iVBORw0KG...",
    "fidelity": 0.5,
    "return_base64": true
  }' 
  https://esmailx50-job.hf.space/api/process
```

### Success Response
```json
{
  "status": "success",
  "count": 1,
  "results": [
    {
      "original_name": "image.png",
      "filename": "api_result_uuid.png",
      "image_url": "https://.../static/results/api_result_uuid.png",
      "image_base64": "iVBORw0KG..." // Only if return_base64 was true
    }
  ]
}
```

### Error Response
```json
{
  "status": "error",
  "message": "Detailed error message here"
}
```

---

## 2. Health Check
Checks if the service is online and returns the compute device being used.

- **Endpoint:** `/api/health`
- **Method:** `GET`

**Success Response:**
```json
{
  "status": "online",
  "device": "cuda" // or "cpu"
}
```

---

## CORS & Integration
Cross-Origin Resource Sharing (CORS) is enabled for all routes. This allows you to call the API directly from browser-based applications (React, Vue, etc.) without hitting "Same-Origin Policy" blocks.

**Javascript Example (Fetch):**
```javascript
const formData = new FormData();
formData.append('image', fileInput.files[0]);
formData.append('fidelity', '0.5');

const response = await fetch('https://esmailx50-job.hf.space/api/process', {
  method: 'POST',
  body: formData
});
const data = await response.json();
console.log(data.results[0].image_url);
```