docs/API.md

Visa Photo Maker Documentation

Overview

Visa Photo Maker is a privacy-first, bilingual web application that automatically processes user-uploaded photos into standard visa/passport photo formats. It uses AI to remove backgrounds and intelligently crops the image to meet specific aspect ratios and composition requirements.

Privacy & Security

Does the server keep my photos? NO.

• Images are processed in RAM (Memory) only.
• The backend receives the file -> Removes Background -> Crops -> Returns the result immediately.
• No save() to disk operations are performed for user images.
• Once the request is finished, the data is discarded by the server's garbage collector.

Features

• AI Background Removal: Uses rembg (U2-Net) to remove complex backgrounds.
• Smart Cropping:
  • Automatically detects the subject.
  • Cleans up semi-transparent noise.
  • Crops excess body parts for correct head-to-body ratios.
  • Ensures no white borders ("Cover Mode").
• Internationalization (i18n):
  • Full support for 6 languages:
    • 🇨🇳 Chinese (ZH)
    • 🇺🇸 English (EN)
    • 🇪🇸 Spanish (ES)
    • 🇫🇷 French (FR)
    • 🇯🇵 Japanese (JA)
    • 🇰🇷 Korean (KO)
  • Dedicated SEO-friendly routes (e.g., /es, /ja).
• Multi-Standard Support:
  • US/India: 2x2 inch (600x600 px)
  • Europe/UK/China: 35x45 mm
  • Japan: 30x40 mm
  • Canada: 50x70 mm
• Queue System: Strict "One at a time" processing to protect server resources.

API Reference

POST /process-image

Uploads an image and returns the processed JPEG.

Parameters (Form Data):

• file: The image file (JPG/PNG).
• width: Target width in pixels (e.g., 600).
• height: Target height in pixels (e.g., 600).

Response:

• Returns a binary JPEG stream of the processed image.

Concurrency:

• The server implements a Global Lock.
• Only 1 request is processed at a time.
• Subsequent requests will wait in a queue until the lock is released.

Architecture

• Frontend: Next.js (React) on Port 3000.
  • Components: src/components/VisaPhotoMaker.tsx (Core Logic).
  • Routes: src/app/[lang]/page.tsx.
• Backend: FastAPI (Python) on Port 13002.
• Process Management: PM2.

Deployment

Managed via PM2:

pm2 list
pm2 restart visa-backend
pm2 restart visa-frontend