API_Usage_Guide.md

# API Usage Guide - Photo Object Removal

## Overview
This guide provides step-by-step instructions for using the Photo Object Removal API to remove objects from images using AI inpainting.

**Base URL:** `https://logicgoinfotechspaces-object-remover.hf.space`  
**Authentication:** Bearer token (optional)

## Quick Start

### 1. Health Check
Verify the API is running:
```bash
curl -H "Authorization: Bearer <API_TOKEN>" \
  https://logicgoinfotechspaces-object-remover.hf.space/health
```
**Response:** `{"status":"healthy"}`

### 2. Upload Image
Upload the image you want to edit:
```bash
curl -H "Authorization: Bearer <API_TOKEN>" \
  -F image=@your_image.jpg \
  https://logicgoinfotechspaces-object-remover.hf.space/upload-image
```
**Response:** `{"id":"9cf61445-f83b-4c97-9272-c81647f90d68","filename":"your_image.jpg"}`

### 3. Upload Mask
Upload a mask showing areas to remove (white/colored areas = remove):
```bash
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. Process Image
Remove objects using the uploaded image and mask:
```bash
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"}' \
  https://logicgoinfotechspaces-object-remover.hf.space/inpaint
```
**Response:** `{"result":"output_b09568698bbd4aa591b1598c01f2f745.png"}`

### 5. View Result
Open the result image in your browser:
```
https://logicgoinfotechspaces-object-remover.hf.space/result/output_b09568698bbd4aa591b1598c01f2f745.png
```

## Alternative Methods

### Method 1: Get Direct URL
Use `/inpaint-url` to get a shareable URL:
```bash
curl -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"image_id":"<image_id>","mask_id":"<mask_id>"}' \
  https://logicgoinfotechspaces-object-remover.hf.space/inpaint-url
```
**Response:** 
```json
{
  "result":"output_xxx.png",
  "url":"https://logicgoinfotechspaces-object-remover.hf.space/download/output_xxx.png"
}
```

### Method 2: One-Step Processing
Upload and process in a single request:
```bash
curl -H "Authorization: Bearer <API_TOKEN>" \
  -F image=@image.jpg \
  -F mask=@mask.jpg \
  https://logicgoinfotechspaces-object-remover.hf.space/inpaint-multipart
```

### Method 3: Download Result
Download the result file:
```bash
curl -L https://logicgoinfotechspaces-object-remover.hf.space/download/output_xxx.png \
  -o result.png
```

## Postman Setup

### 1. 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

### 2. 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

### 3. Process Image
- **Method:** POST
- **URL:** `https://logicgoinfotechspaces-object-remover.hf.space/inpaint`
- **Headers:** 
  - `Authorization: Bearer <API_TOKEN>`
  - `Content-Type: application/json`
- **Body:** raw JSON
```json
{
  "image_id": "9cf61445-f83b-4c97-9272-c81647f90d68",
  "mask_id": "d044a390-dde2-408a-b7cf-d508385e56ed"
}
```

## Mask Creation Guide

### 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

### Creating Masks
1. **Paint Method:** Use any image editor to paint white/colored areas over objects you want to remove
2. **Transparency Method:** Create a PNG with transparent areas where you want objects removed
3. **Grayscale Method:** Create a black image and paint white areas over objects to remove

### Tips
- Use high contrast (white on black) for best results
- Make sure mask areas are clearly defined
- Avoid thin lines or small details in the mask

## Error Handling

### Common Errors

**422 Unprocessable Entity**
- **Cause:** Missing required fields or invalid file format
- **Solution:** Check file upload and field names

**404 Not Found**
- **Cause:** Invalid image_id or mask_id
- **Solution:** Re-upload files to get fresh IDs

**401 Unauthorized**
- **Cause:** Missing or invalid API token
- **Solution:** Add correct Authorization header

**403 Forbidden**
- **Cause:** Wrong API token
- **Solution:** Use the correct token you configured

### Troubleshooting

**File Upload Issues in Postman:**
- Remove warning icons next to filenames
- Re-select files if warning appears
- Try different file formats (PNG, JPG)
- Check file isn't corrupted

**Slow Processing:**
- Large images take longer to process
- Typical processing time: 1-3 seconds
- Wait for completion before checking results

## Complete Workflow Example

```bash
# 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=@photo.jpg \
  https://logicgoinfotechspaces-object-remover.hf.space/upload-image

# 3. Upload mask
curl -H "Authorization: Bearer <API_TOKEN>" \
  -F mask=@mask.png \
  https://logicgoinfotechspaces-object-remover.hf.space/upload-mask

# 4. Process (replace with actual IDs from steps 2&3)
curl -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"image_id":"IMAGE_ID","mask_id":"MASK_ID"}' \
  https://logicgoinfotechspaces-object-remover.hf.space/inpaint

# 5. View result (replace with actual filename from step 4)
# Open in browser: https://logicgoinfotechspaces-object-remover.hf.space/result/OUTPUT_FILENAME
```

## API Endpoints Summary

| Method | Endpoint | Description | Auth Required |
|--------|----------|-------------|---------------|
| GET | `/health` | Health check | No |
| GET | `/` | API information | No |
| POST | `/upload-image` | Upload image file | Optional |
| POST | `/upload-mask` | Upload mask file | Optional |
| POST | `/inpaint` | Process with IDs | Optional |
| POST | `/inpaint-url` | Process with URL response | Optional |
| POST | `/inpaint-multipart` | One-step processing | Optional |
| GET | `/download/{filename}` | Download result | No |
| GET | `/result/{filename}` | View result in browser | No |
| GET | `/logs` | View processing logs | Optional |
| GET | `/docs` | API documentation | No |

## Support

For issues or questions:
1. Check the API documentation at `/docs`
2. Verify your request format matches examples
3. Ensure files are properly uploaded
4. Check authentication token is correct