HTTP_API_Documentation.txt

HTTP API Documentation - Photo Object Removal Service

Base URL: https://logicgoinfotechspaces-object-remover.hf.space

Authentication:
- Optional Bearer token authentication
- Set API_TOKEN environment variable on server to enable auth
- Send header: Authorization: Bearer <API_TOKEN>
- If API_TOKEN not set, all endpoints are publicly accessible
- Inpainting work is delegated to Google Gemini/Imagen edit API; no GPU is needed on the server.
- Uploads are stored in MongoDB GridFS (database `object_remover`); the IDs returned by upload endpoints are fetched from GridFS when processing.

Available Endpoints:

1. GET /health
   - Health check endpoint
   - Returns: {"status":"healthy"}
   - No authentication required

2. POST /upload-image
   - Upload an image file for processing
   - Content-Type: multipart/form-data
   - Form field: image (file)
   - Returns: {"id":"<image_id>","filename":"original_name.png"}
   - Supported formats: PNG, JPG, JPEG

3. POST /upload-mask
   - Upload a mask file indicating areas to remove
   - Content-Type: multipart/form-data
   - Form field: mask (file)
   - Returns: {"id":"<mask_id>","filename":"mask.png"}
   - Mask formats:
     * RGBA PNG: pixels with alpha=0 are treated as areas to remove
     * RGB/Grayscale: pixels with value > 0 are treated as areas to remove

4. POST /inpaint
   - Process inpainting using uploaded image and mask IDs
   - Content-Type: application/json
   - Body: {"image_id":"<image_id>","mask_id":"<mask_id>","prompt":"optional text about what to remove"}
   - Returns: {"result":"output_xxx.png"}
   - Simple response with just the filename

5. POST /inpaint-url
   - Same as /inpaint but returns JSON with public download URL
   - Content-Type: application/json
   - Body: {"image_id":"<image_id>","mask_id":"<mask_id>","prompt":"optional text about what to remove"}
   - Returns: {"result":"output_xxx.png","url":"https://.../download/output_xxx.png"}
   - Use this endpoint if you need a shareable URL

6. POST /inpaint-multipart
   - Process inpainting with direct file upload (no separate upload steps)
   - Content-Type: multipart/form-data
   - Form fields: image (file), mask (file), prompt (optional text)
   - Returns: {"result":"output_xxx.png","url":"https://.../download/output_xxx.png"}

7. GET /download/{filename}
   - Download result image by filename
   - Public endpoint (no authentication required)
   - Returns: image/png (binary data)
   - Can be opened directly in browser

8. GET /result/{filename}
   - View result image directly in browser
   - Public endpoint (no authentication required)
   - Returns: image/png with proper content-type for viewing
   - Optimized for browser display

CURL EXAMPLES:

1. Health Check:
curl -H "Authorization: Bearer <API_TOKEN>" \
  https://logicgoinfotechspaces-object-remover.hf.space/health

2. Upload Image:
curl -H "Authorization: Bearer <API_TOKEN>" \
  -F image=@image.png \
  https://logicgoinfotechspaces-object-remover.hf.space/upload-image
# Response: {"id":"9cf61445-f83b-4c97-9272-c81647f90d68","filename":"image.png"}

3. Upload Mask:
curl -H "Authorization: Bearer <API_TOKEN>" \
  -F mask=@mask.png \
  https://logicgoinfotechspaces-object-remover.hf.space/upload-mask
# Response: {"id":"d044a390-dde2-408a-b7cf-d508385e56ed","filename":"mask.png"}

4. Inpaint (returns simple JSON):
curl -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"image_id":"9cf61445-f83b-4c97-9272-c81647f90d68","mask_id":"d044a390-dde2-408a-b7cf-d508385e56ed","prompt":"Remove the car and repair the road"}' \
  https://logicgoinfotechspaces-object-remover.hf.space/inpaint
# Response: {"result":"output_b09568698bbd4aa591b1598c01f2f745.png"}

5. Inpaint-URL (returns JSON with public URL):
curl -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"image_id":"9cf61445-f83b-4c97-9272-c81647f90d68","mask_id":"d044a390-dde2-408a-b7cf-d508385e56ed","prompt":"Remove the car and repair the road"}' \
  https://logicgoinfotechspaces-object-remover.hf.space/inpaint-url
# Response: {"result":"output_b09568698bbd4aa591b1598c01f2f745.png","url":"https://logicgoinfotechspaces-object-remover.hf.space/download/output_b09568698bbd4aa591b1598c01f2f745.png"}

6. Inpaint Multipart (one-step processing):
curl -H "Authorization: Bearer <API_TOKEN>" \
  -F image=@image.png \
  -F mask=@mask.png \
  https://logicgoinfotechspaces-object-remover.hf.space/inpaint-multipart
# Response: {"result":"output_xxx.png","url":"https://logicgoinfotechspaces-object-remover.hf.space/download/output_xxx.png"}

7. Download Result (public, no auth):
curl -L https://logicgoinfotechspaces-object-remover.hf.space/download/output_b09568698bbd4aa591b1598c01f2f745.png \
  -o result.png

8. View Result in Browser (public, no auth):
curl -L https://logicgoinfotechspaces-object-remover.hf.space/result/output_b09568698bbd4aa591b1598c01f2f745.png \
  -o result.png

POSTMAN EXAMPLES:

1. Health Check:
   Method: GET
   URL: https://logicgoinfotechspaces-object-remover.hf.space/health
   Headers: Authorization: Bearer <API_TOKEN>

2. Upload Image:
   Method: POST
   URL: https://logicgoinfotechspaces-object-remover.hf.space/upload-image
   Headers: Authorization: Bearer <API_TOKEN>
   Body: form-data
   Key: image, Type: File, Value: select your image file

3. Upload Mask:
   Method: POST
   URL: https://logicgoinfotechspaces-object-remover.hf.space/upload-mask
   Headers: Authorization: Bearer <API_TOKEN>
   Body: form-data
   Key: mask, Type: File, Value: select your mask file

4. Inpaint (returns simple JSON):
   Method: POST
   URL: https://logicgoinfotechspaces-object-remover.hf.space/inpaint
   Headers: 
     - Authorization: Bearer <API_TOKEN>
     - Content-Type: application/json
   Body: raw JSON
   {
     "image_id": "9cf61445-f83b-4c97-9272-c81647f90d68",
     "mask_id": "d044a390-dde2-408a-b7cf-d508385e56ed",
     "prompt": "Remove the car and restore the street"
   }

5. Inpaint Multipart (one-step):
   Method: POST
   URL: https://logicgoinfotechspaces-object-remover.hf.space/inpaint-multipart
   Headers: Authorization: Bearer <API_TOKEN>
   Body: form-data
   Key: image, Type: File, Value: select your image file
   Key: mask, Type: File, Value: select your mask file
   Key: prompt, Type: Text, Value: describe what to remove (optional)

IMPORTANT NOTES:

Authentication:
- If API_TOKEN is set on the server, include Authorization header
- If API_TOKEN is not set, omit Authorization header
- /download/{filename} is always public (no auth required)

Mask Formats:
- RGBA PNG: pixels with alpha=0 are treated as areas to remove
- RGB/Grayscale: pixels with value > 0 are treated as areas to remove
- Create mask by painting white/colored areas over objects you want to remove

Error Handling:
- 404 Not Found on /inpaint: server restarted, IDs expired - re-upload files
- 401 Unauthorized: missing or invalid API_TOKEN
- 403 Forbidden: wrong API_TOKEN

Workflow Options:
1. Two-step: upload-image → upload-mask → inpaint (get filename)
2. One-step: inpaint-multipart (upload and process in single request)
3. Direct access: use /download/{filename} or /result/{filename} with returned filename

Browser Access:
- Paste any /download/{filename} or /result/{filename} URL directly in Chrome to view the result
- No authentication required for download/view URLs
- /result/{filename} is optimized for browser viewing
- Examples: 
  * https://logicgoinfotechspaces-object-remover.hf.space/download/output_b09568698bbd4aa591b1598c01f2f745.png
  * https://logicgoinfotechspaces-object-remover.hf.space/result/output_b09568698bbd4aa591b1598c01f2f745.png