# API Usage Guide

This document describes how to use the background removal API.

---

## Base URL

- Local: `http://localhost:8000`
- Production: `http://localhost:8000`

---

## Endpoints

### 1. API Info

```
GET /
```

Returns service metadata and links.

**Response:**
```json
{
  "service": "withoutbg-api",
  "version": "1.0.2",
  "docs": "/docs",
  "health": "/api/health"
}
```

---

### 2. Health Check

```
GET /api/health
```

Verify the API is running and models are loaded.

**Response:**
```json
{
  "status": "healthy",
  "version": "1.0.2",
  "service": "withoutbg-api",
  "models_loaded": true
}
```

---

### 3. Remove Background

```
POST /api/remove-background
Content-Type: multipart/form-data
```

Remove the background from an image and return the result.

#### Parameters

| Name    | Type   | Required | Default | Description                                                |
|---------|--------|----------|---------|------------------------------------------------------------|
| `file`  | File   | Yes      | —       | Image file (PNG, JPEG, WebP)                               |
| `format`| String | No       | `webp`  | Output format: `webp`, `png`, or `jpg`                     |
| `quality` | Integer | No     | `95`    | Compression quality for WebP/JPEG (1–100)                  |

#### Request Example (curl)

```bash
# WebP output (default)
curl -X POST https://your-api.com/api/remove-background \
  -F "file=@/path/to/photo.jpg" \
  -o result.webp

# PNG output
curl -X POST https://your-api.com/api/remove-background \
  -F "file=@photo.png" \
  -F "format=png" \
  -o result.png

# JPEG output with quality
curl -X POST https://your-api.com/api/remove-background \
  -F "file=@photo.jpg" \
  -F "format=jpg" \
  -F "quality=90" \
  -o result.jpg
```

#### Request Example (Python)

```python
import requests

url = "https://your-api.com/api/remove-background"

with open("photo.jpg", "rb") as f:
    response = requests.post(
        url,
        files={"file": ("photo.jpg", f, "image/jpeg")},
        data={"format": "webp", "quality": 95},
    )

if response.ok:
    with open("result.webp", "wb") as out:
        out.write(response.content)
else:
    print(response.json())
```

#### Request Example (JavaScript / Fetch)

```javascript
const formData = new FormData();
formData.append("file", imageFile);
formData.append("format", "webp");
formData.append("quality", "95");

const response = await fetch("https://your-api.com/api/remove-background", {
  method: "POST",
  body: formData,
});

if (response.ok) {
  const blob = await response.blob();
  // Use blob (e.g. create download link, display in img)
} else {
  const error = await response.json();
  console.error(error.detail);
}
```

#### Response

- **Success (200):** Binary image (WebP, PNG, or JPEG)
- **Content-Type:** `image/webp`, `image/png`, or `image/jpeg`
- **Content-Disposition:** `inline; filename=withoutbg.{format}`

#### Response Headers

| Header                | Description                                                                 |
|-----------------------|-----------------------------------------------------------------------------|
| `X-Format-Fallback`   | Present if WebP was requested but PNG was returned (e.g. `X-Format-Fallback: png`) |

---

## Processing Behavior

- Input image is centered on a transparent square canvas (height × height)
- Output is resized so the longest side is at most 1000px
- Output size is limited to ~50KB; if larger, the API may compress further
- Supported input formats: PNG, JPEG, WebP

---

## Error Responses

Errors return JSON with a `detail` field.

| Status | Meaning                    | Example `detail`                         |
|--------|----------------------------|-----------------------------------------|
| 400    | Bad request                | `File too small (64 bytes)...`           |
| 400    | Invalid image              | `Invalid or unsupported image format`    |
| 500    | Processing error           | `Processing failed: ...`                 |
| 503    | Service not ready          | `Models not loaded. Server may still be starting up.` |

**Example:**
```json
{
  "detail": "File too small (64 bytes). Verify the file exists and use full path: -F 'file=@/path/to/image.webp'"
}
```

---

## Interactive Documentation

When the API is running, Swagger UI is available at:

```
GET /docs
```

Use it to try endpoints from the browser.
