API_REFERENCE.md

# EL HELAL Studio API Reference

This document provides a comprehensive overview of all available REST API endpoints for the headless EL HELAL Studio image processing backend.

The backend is built with **FastAPI**. All JSON responses follow standard HTTP status codes. By default, the API runs on `http://localhost:8000`.
An interactive Swagger UI is also automatically generated and available at `http://localhost:8000/docs`.

---

## Table of Contents

1. [Core Pipeline](#1-core-pipeline)
2. [Global Settings](#2-global-settings)
3. [Frames & Assets](#3-frames--assets)
4. [State & Utility](#4-state--utility)
5. [Backup & Restore](#5-backup--restore)
6. [Static Files](#6-static-files)

---

## 1. Core Pipeline

These endpoints manage the actual upload and processing of images through the AI pipeline.

### Upload Image

Uploads an initial image, corrects EXIF orientation, and generates a lightweight thumbnail for UI previews.

- **URL:** `/upload`
- **Method:** `POST`
- **Content-Type:** `multipart/form-data`
- **Parameters:**
  - `file` (File, required): The raw image file (JPG/PNG/etc).
- **Success Response:** (200 OK)
  ```json
  {
    "id": "uuid-string",
    "filename": "original_name.jpg",
    "thumb_url": "/static/uploads/uuid-string_thumb.jpg",
    "width": 4000,
    "height": 3000
  }
  ```

### Process Image

Passes an uploaded image through the configured AI processing steps (Restoration, Crop, Background Removal, AI Color Correction, Retouching, and Layout Generation).

- **URL:** `/process/{file_id}`
- **Method:** `POST`
- **Content-Type:** `application/x-www-form-urlencoded` or `multipart/form-data`
- **Path Parameters:**
  - `file_id` (string, required): The UUID returned from the `/upload` endpoint.
- **Form Parameters (All Optional with defaults):**
  - `name` (string): Text string to render in the layout.
  - `id_number` (string): ID string to render in the layout.
  - `do_restore` (bool, default: `false`): Enable GFPGAN/CodeFormer face restoration.
  - `fidelity` (float, default: `0.5`): Restoration fidelity balance.
  - `do_rmbg` (bool, default: `true`): Enable BRIA-RMBG-2.0 background removal.
  - `do_color` (bool, default: `true`): Enable AI ColorUNet color correction.
  - `do_retouch` (bool, default: `true`): Enable skin blemish retouching.
  - `do_crop` (bool, default: `true`): Enable auto-cropping to 4x6.
  - `add_studio_name` (bool, default: `true`): Render studio name on layout.
  - `add_logo` (bool, default: `true`): Render studio logo on layout.
  - `add_date` (bool, default: `true`): Render current date on layout.
  - `frame_color` (string): Custom hex color for the layout frame (e.g., `#ffffff`).
  - `frame_name` (string): Filename of a custom overlay frame.
  - `x1`, `y1`, `x2`, `y2` (int): Bounding box coordinates for a manual crop override.
- **Success Response:** (200 OK)
  ```json
  {
    "id": "uuid-string",
    "result_url": "/static/results/uuid-string_layout.jpg",
    "preview_url": "/static/results/uuid-string_preview.jpg"
  }
  ```
- **Error Responses:**
  - `404 Not Found`: If the `file_id` does not exist in the uploads directory.
  - `503 Service Unavailable`: If the AI models are still loading (`models["ready"] == False`).
  - `500 Internal Server Error`: For pipeline processing exceptions.

---

## 2. Global Settings

Manage system-wide configuration such as retouching sensitivity and text defaults.

### Get Settings

Fetches the current backend configuration.

- **URL:** `/settings`
- **Method:** `GET`
- **Success Response:** (200 OK)
  ```json
  {
    "retouch": {
      "enabled": true,
      "sensitivity": 3.0,
      "tone_smoothing": 0.6
    },
    "layout": {
      "default_frame_color": "#ffffff"
    }
  }
  ```

### Update Settings

Merges a JSON payload into the existing `config/settings.json`.

- **URL:** `/settings`
- **Method:** `POST`
- **Content-Type:** `application/json`
- **Body:** A partial or complete settings JSON object.
- **Success Response:** (200 OK)
  ```json
  {
    "status": "success"
  }
  ```

---

## 3. Frames & Assets

Manage custom layout overlay frames.

### List Frames

- **URL:** `/frames`
- **Method:** `GET`
- **Success Response:** (200 OK)
  ```json
  {
    "frames": [
      {
        "filename": "frame-example.png",
        "url": "/assets/frame-example.png"
      }
    ]
  }
  ```

### Upload Frame

- **URL:** `/frames`
- **Method:** `POST`
- **Content-Type:** `multipart/form-data`
- **Parameters:**
  - `file` (File, required): A PNG/JPG/WEBP image file.
- **Success Response:** (200 OK)
  ```json
  {
    "status": "success",
    "frame": {
      "filename": "frame-1234abcd.png",
      "url": "/assets/frame-1234abcd.png"
    }
  }
  ```

### Delete Frame

- **URL:** `/frames/{filename}`
- **Method:** `DELETE`
- **Path Parameters:**
  - `filename` (string, required): The exact internal filename (must start with `frame-`).
- **Success Response:** (200 OK)
  ```json
  {
    "status": "success"
  }
  ```

---

## 4. State & Utility

### Get API Status

Check if background initialization (like loading the PyTorch machine learning models) is complete. You should ping this endpoint before allowing a user to click "Process".

- **URL:** `/status`
- **Method:** `GET`
- **Success Response:** (200 OK)
  ```json
  {
    "ai_ready": true
  }
  ```

### Clear All Storage

Manually purges all stored files (`uploads/`, `processed/`, and `results/`). Normally, a background cleanup task does this atomically for files older than 24 hours.

- **URL:** `/clear-all`
- **Method:** `POST`
- **Success Response:** (200 OK)
  ```json
  {
    "status": "success",
    "removed_count": 15
  }
  ```

---

## 5. Backup & Restore

### Export Backup

Packages the configurations, uploaded frames, and an optionally provided frontend client state into a `.zip` archive.

- **URL:** `/backup/export`
- **Method:** `POST`
- **Content-Type:** `application/json`
- **Body:**
  - `client_data` (dict, optional): Any frontend state to include in the backup zip.
- **Success Response:** (200 OK)
  - Returns a binary `.zip` file download via `StreamingResponse`.

### Import Backup

Restores configuration and assets from a previously exported `.zip`.

- **URL:** `/backup/import`
- **Method:** `POST`
- **Content-Type:** `multipart/form-data`
- **Parameters:**
  - `file` (File, required): The `.zip` backup file.
- **Success Response:** (200 OK)
  ```json
  {
    "status": "success",
    "client_data": { ... }
  }
  ```

---

## 6. Static Files

The FastAPI server mounts internal directories for direct read-only access.

- **Images & Results:** `GET /static/...`
  - Maps to the `./storage/` directory.
  - _Usage:_ `/static/uploads/{id}_thumb.jpg` or `/static/results/{id}_layout.jpg`
- **App Assets:** `GET /assets/...`
  - Maps to the `./assets/` directory.
  - _Usage:_ `/assets/frame-custom.png`