API Documentation

The Ghost Mannequin API provides powerful endpoints for batch processing product photos with AI-powered ghost mannequin effects. All API requests should be made to your server base URL.

Quick Start

Get started with the Ghost Mannequin API in minutes. All endpoints return JSON responses and support CORS for browser-based applications.

const formData = new FormData();
formData.append('files', imageFile);

const response = await fetch('http://localhost:8000/upload-batch/', {
  method: 'POST',
  body: formData
});

const batch = await response.json();
console.log(batch.batch_id);

Getting Started

To use the API, you'll need to subscribe to a plan and obtain your API authentication token.

Step 1: Create an Account & Subscribe

Go to Sign Up to create your account
Visit the Pricing Page to subscribe to a plan

API Access Required

You must subscribe to the Web API plan to make programmatic API requests. The Batch Subscription only provides web interface access.

Step 2: Get Your API Token

After subscribing to the Web API plan, go to your Account Page
Your Firebase authentication token will be displayed in the "API Authentication" section
Click "Copy" to copy the token to your clipboard
The token expires after 1 hour - use the "Refresh Token" button to get a new one

Step 3: Authenticate Your Requests

Include your token in the Authorization header of all API requests:

// JavaScript/Fetch
const response = await fetch('https://your-api.com/upload-batch/', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_FIREBASE_TOKEN_HERE'
  },
  body: formData
});

// cURL
curl -X POST https://your-api.com/upload-batch/ \
  -H "Authorization: Bearer YOUR_FIREBASE_TOKEN_HERE" \
  -F "files=@image1.jpg" \
  -F "files=@image2.jpg"

// Python
import requests

headers = {
    'Authorization': 'Bearer YOUR_FIREBASE_TOKEN_HERE'
}
files = [('files', open('image.jpg', 'rb'))]
response = requests.post('https://your-api.com/upload-batch/',
                         headers=headers, files=files)

Token Management

Tokens expire after 1 hour. If you receive a 401 Unauthorized error, refresh your token from the Account page or programmatically using the Firebase SDK.

Base URL

https://ghost-mannequin-api-824289311857.us-central1.run.app

All API endpoints are relative to this base URL. For local development, use http://localhost:8000.

Endpoints

POST /upload-batch/

Upload multiple images for batch processing with ghost mannequin effect.

Query Parameters

Parameter	Type	Required	Description
background_color	string	Optional	Background color for processed images. Default: white
mannequin_size	string	Optional	Mannequin size: toddler, child, teen, adult. Default: toddler

Request Body

Field	Type	Required	Description
files	File[]	Required	Array of image files (JPG, PNG).

Example Request

// JavaScript
const formData = new FormData();
files.forEach(file => formData.append('files', file));

const response = await fetch(
  'http://localhost:8000/upload-batch/?background_color=white',
  { method: 'POST', body: formData }
);

GET /batch-status/{batch_id}

Check the processing status of a batch and retrieve URLs for completed images.

Path Parameters

Parameter	Type	Description
batch_id	string (UUID)	The batch ID from upload-batch

Polling Recommendation

Poll every 2-3 seconds until status is "completed" or "partial_failure".

POST /upload-single/

Upload a single image file without processing.

Status Codes

Code	Description
200	Success
400	Bad Request
404	Not Found
500	Internal Server Error

Batch Statuses

Status	Description
uploaded	Queued for processing
processing	Currently processing
completed	All files processed
partial_failure	Some files failed

Complete Example

async function processImages(files) {
  // 1. Upload
  const formData = new FormData();
  files.forEach(f => formData.append('files', f));

  const batch = await fetch('/upload-batch/', {
    method: 'POST', body: formData
  }).then(r => r.json());

  // 2. Poll
  while (true) {
    const status = await fetch(`/batch-status/${batch.batch_id}`)
      .then(r => r.json());

    if (status.status === 'completed') return status;
    await new Promise(r => setTimeout(r, 2000));
  }
}

Rate Limits

Recommended limits:

Maximum 100 images per batch
Poll no more than once per second
Maximum file size: 10MB

Need Help?

Check examples above
Review error messages
Try the web interface