# Lushai AI Background Removal — Remove.bg Compatible REST API
Engineered by Lushai Dev (https://lushai.dev)

## 1. Overview & Capabilities
Lushai AI Background Removal API is an ultra-fast, high-precision computer vision API designed as a direct drop-in replacement for Remove.bg. It strips backgrounds from portrait, product, animal, and object photos cleanly in under 3 seconds, delivering a transparent PNG or base64 JSON payload.

- Base URL: https://lushai.dev
- Endpoint: `POST /api/v1/remove-bg`
- Documentation Endpoint: `GET /api/v1/remove-bg`

---

## 2. Pricing & Wallet Billing
Lushai Dev delivers enterprise-grade AI background removal at a fraction of standard commercial prices:

- **Ultra-Affordable Pricing**: **₹1 INR for 30 requests / ₹10 for 300 requests** (₹0.0333 per image).
- **Compared to Competitors**: Over 98% cheaper than Remove.bg (which charges up to $0.20–$0.90 per image).
- **Billing Model**: Prepaid Developer Wallet (`wallet_balance_inr`).
- **Atomic Precision**: Charges are atomically deducted per successful background extraction. If processing fails, the amount is automatically refunded to your wallet.
- **Top-up**: Add funds anytime in your developer dashboard at `https://lushai.dev/dashboard`.

---

## 3. Authentication & Headers
All requests require a valid Lushai Developer API Key:
- `X-API-Key: lsh_xxxxxxxx_xxxxxxxx`
- Or `Authorization: Bearer lsh_xxxxxxxx_xxxxxxxx`

---

## 4. Endpoints & Request Specifications

### `POST /api/v1/remove-bg`

#### Accepted Content-Types:
1. `multipart/form-data`
2. `application/json`
3. `image/jpeg`, `image/png`, `image/webp` (Direct binary stream)

#### Parameters:
- `image_file` (File, multipart): Binary image file to process.
- `image_url` (string, multipart or JSON): Publicly accessible image URL.
- `image_file_b64` / `image_b64` (string, JSON): Base64-encoded image string.
- `format` (string, optional): `"png"` (default binary stream) or `"json"` (returns base64 result in JSON).
- `size` (string, optional): `"auto"`, `"preview"`, `"full"` (compatibility alias; returns full resolution).
- `model` (string, optional): AI neural model selection:
  - `"ls_bg_v1"` (default): Balanced Core model for everyday products, e-commerce catalog, and avatars.
  - `"ls_bg_v1_pro"`: Studio Ultra HD Precision model for fine hair strands, fur, lace, and complex studio portraits.
  - `"ls_bg_v1_flash"`: Turbo High-Speed model with ultra-low latency for high-volume batch processing and apps.

#### Response Formats:
- **Default (Binary PNG)**:
  - Content-Type: `image/png`
  - Response Body: Binary transparent PNG stream
  - Response Headers:
    - `X-Charged-INR`: `0.01`
    - `X-Wallet-Balance-Remaining`: Developer remaining wallet balance
    - `X-Processed-By`: `Lushai-AI-Vision-Engine`
- **JSON Mode (`format=json`)**:
  - Content-Type: `application/json`
  - Body:
    ```json
    {
      "status": "success",
      "data": {
        "result_b64": "iVBORw0KGgoAAAANSUhEUgAA...",
        "mime_type": "image/png",
        "size_bytes": 77106
      },
      "charged_inr": 0.01,
      "wallet_balance_remaining_inr": 49.96
    }
    ```

---

## 5. Code Examples

### cURL (Direct Binary PNG Output)
```bash
curl -X POST https://lushai.dev/api/v1/remove-bg \
  -H "X-API-Key: YOUR_LUSHAI_API_KEY" \
  -F "image_file=@photo.jpg" \
  -o no-bg.png
```

### cURL (Using Image URL)
```bash
curl -X POST https://lushai.dev/api/v1/remove-bg \
  -H "X-API-Key: YOUR_LUSHAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"image_url": "https://example.com/shoe.jpg", "format": "png"}' \
  -o shoe-cutout.png
```

### Node.js / JavaScript (Fetch)
```javascript
import fs from 'fs';

const formData = new FormData();
const imageBuffer = fs.readFileSync('input.jpg');
formData.append('image_file', new Blob([imageBuffer], { type: 'image/jpeg' }), 'input.jpg');

const response = await fetch('https://lushai.dev/api/v1/remove-bg', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.LUSHAI_API_KEY,
  },
  body: formData,
});

if (response.ok) {
  const arrayBuffer = await response.arrayBuffer();
  fs.writeFileSync('output.png', Buffer.from(arrayBuffer));
  console.log('Done! Cost: ₹' + response.headers.get('x-charged-inr'));
} else {
  console.error('Error:', await response.json());
}
```

### Python (Requests)
```python
import requests

url = "https://lushai.dev/api/v1/remove-bg"
headers = {"X-API-Key": "YOUR_LUSHAI_API_KEY"}

with open("product.jpg", "rb") as img:
    response = requests.post(url, headers=headers, files={"image_file": img})

if response.status_code == 200:
    with open("product-no-bg.png", "wb") as out:
        out.write(response.content)
    print("Background removed successfully! Charged: ₹" + response.headers.get("X-Charged-INR", "0.01"))
else:
    print("Failed:", response.json())
```

### PHP (cURL)
```php
<?php
$ch = curl_init('https://lushai.dev/api/v1/remove-bg');
$cfile = new CURLFile('portrait.jpg', 'image/jpeg', 'portrait.jpg');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: YOUR_LUSHAI_API_KEY'
    ],
    CURLOPT_POSTFIELDS => [
        'image_file' => $cfile
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode === 200) {
    file_put_contents('portrait-no-bg.png', $response);
    echo "Saved cutout to portrait-no-bg.png\n";
} else {
    echo "Error: " . $response . "\n";
}
curl_close($ch);
```

---

## 6. HTTP Error Codes
- `401 Unauthorized`: API key is missing or invalid.
- `402 Payment Required`: Wallet balance is insufficient (below ₹0.01). Top up at https://lushai.dev/dashboard.
- `400 Bad Request`: Missing image file or malformed request.
- `413 Payload Too Large`: Image file exceeds 20MB.
- `500 Internal Server Error`: Processing failed; automatic wallet refund issued.