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

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

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

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

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

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

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);