Add API documentation for programmatic access

API_DOCUMENTATION.md

@@ -0,0 +1,118 @@
+# 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);
+```