docs/guides/quick-start.md

Quick Start Guide

Get up and running with BackgroundFX Pro in just 5 minutes! This guide will walk you through the essential steps to start removing backgrounds from your images.

🚀 Installation Options

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/backgroundfx/backgroundfx-pro.git
cd backgroundfx-pro

# Start with Docker Compose
docker-compose up -d

# Access the application
open http://localhost:3000

Option 2: Local Development

# Backend setup
cd api
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
uvicorn main:app --reload

# Frontend setup (new terminal)
cd web
npm install
npm run dev

Option 3: Cloud Deployment

🔑 API Authentication

1. Register for an API Key

curl -X POST https://api.backgroundfx.pro/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "secure_password",
    "name": "Your Name"
  }'

2. Get Your Access Token

curl -X POST https://api.backgroundfx.pro/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your@email.com",
    "password": "secure_password"
  }'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "your@email.com",
    "plan": "free"
  }
}

🖼️ Your First Background Removal

Using the Web Interface

1. Navigate to http://localhost:3000
2. Click "Upload Image" or drag and drop
3. Wait for processing (typically 1-2 seconds)
4. Download your result!

Using the API

# Remove background from an image
curl -X POST https://api.backgroundfx.pro/v1/process/remove-background \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "quality=high" \
  -F "return_mask=true"

Using Python SDK

from backgroundfx import BackgroundFX

# Initialize client
client = BackgroundFX(api_key="YOUR_API_KEY")

# Remove background
result = client.remove_background(
    image_path="photo.jpg",
    quality="high",
    return_mask=True
)

# Save result
result.save("output.png")

Using JavaScript SDK

import { BackgroundFX } from 'backgroundfx-js';

// Initialize client
const client = new BackgroundFX({ apiKey: 'YOUR_API_KEY' });

// Remove background
const result = await client.removeBackground({
  file: imageFile,
  quality: 'high',
  returnMask: true
});

// Get result URL
console.log(result.imageUrl);

🎨 Adding Custom Backgrounds

Solid Color Background

# Replace with solid color
result = client.replace_background(
    image_id="result_id",
    background="#FF5733"  # Hex color
)

Gradient Background

# Replace with gradient
result = client.replace_background(
    image_id="result_id",
    background="linear-gradient(45deg, #667eea, #764ba2)"
)

Image Background

# Replace with another image
result = client.replace_background(
    image_id="result_id",
    background_path="background.jpg"
)

AI-Generated Background

# Generate and apply AI background
background = client.generate_background(
    prompt="sunny beach with palm trees",
    style="realistic"
)

result = client.replace_background(
    image_id="result_id",
    background_id=background.id
)

📦 Batch Processing

Process multiple images at once:

# Process batch of images
job = client.process_batch(
    images=["photo1.jpg", "photo2.jpg", "photo3.jpg"],
    options={
        "quality": "high",
        "model": "u2net",
        "return_mask": True
    }
)

# Check job status
while job.status != "completed":
    job.refresh()
    print(f"Progress: {job.progress}%")
    time.sleep(1)

# Get results
for result in job.results:
    result.save(f"output_{result.id}.png")

🎥 Video Processing

Remove backgrounds from videos:

# Process video
video_job = client.process_video(
    video_path="input.mp4",
    options={
        "quality": "high",
        "fps": 30,
        "background": "#00FF00"  # Green screen
    }
)

# Monitor progress
video_job.on_progress(lambda p: print(f"Processing: {p}%"))

# Wait for completion
video_job.wait()

# Download result
video_job.download("output.mp4")

⚙️ Configuration Options

Processing Models

Model	Speed	Quality	Best For
rembg	Fast	Good	General use
u2net	Medium	Excellent	Complex edges
deeplab	Slow	Best	Professional
custom	Varies	Highest	Specific use cases

Quality Settings

Setting	Resolution	Processing Time	Use Case
low	512px	~0.5s	Previews
medium	1024px	~1s	Web use
high	2048px	~2s	Print
ultra	4096px	~5s	Professional

🔄 Real-time Processing with WebSockets

// Connect to WebSocket
const ws = new WebSocket('wss://api.backgroundfx.pro/ws');

// Subscribe to job updates
ws.send(JSON.stringify({
  action: 'subscribe',
  job_id: 'job_uuid'
}));

// Handle updates
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Progress: ${data.progress}%`);
};

📊 Usage Monitoring

Check your API usage:

curl -X GET https://api.backgroundfx.pro/v1/user/usage \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "images_processed": 1234,
  "videos_processed": 56,
  "storage_used_mb": 2456,
  "api_calls": 8901,
  "billing_period": "2024-01-01 to 2024-01-31",
  "plan_limits": {
    "images_per_month": 10000,
    "storage_gb": 100,
    "api_calls_per_hour": 1000
  }
}

🚨 Common Issues

Issue: "File too large"

Solution: Ensure your file is under 50MB for images, 500MB for videos.

Issue: "Rate limit exceeded"

Solution: Upgrade your plan or implement request throttling.

Issue: "Poor edge quality"

Solution: Use higher quality settings or the u2net model.

Issue: "Processing timeout"

Solution: Use batch processing for multiple files or reduce file size.

📚 Next Steps

• API Reference - Complete API documentation
• Tutorials - Step-by-step guides
• Best Practices - Optimization tips
• Examples - Sample code

🆘 Need Help?

• 📧 Email: support@backgroundfx.pro
• 💬 Discord: Join our community
• 📚 Forum: Community Forum

---

Ready to build? Start integrating BackgroundFX Pro into your application today!