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
2. Global Settings
3. Frames & Assets
4. State & Utility
5. Backup & Restore
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)

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

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

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

  {
    "status": "success"
  }
  

---

3. Frames & Assets

Manage custom layout overlay frames.

List Frames

• URL: /frames
• Method: GET
• Success Response: (200 OK)

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

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

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

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

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

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