# StagingSpaces API

> AI-powered virtual staging for real estate. Stage empty rooms with photorealistic furniture in seconds.

## Quick Start

1. Sign up at https://studio.stagingspaces.app
2. Click "API" in the sidebar → Create Key (you get 10 free credits)
3. (Optional) Settings tab → Add Payment Method to buy credits
3. Stage your first image:

```bash
curl -X POST https://stagingspaces-production-6fb7.up.railway.app/api/v1/stage \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@empty_room.jpg" \
  -F "style=modern"
```

## Base URL

Production: https://stagingspaces-production-6fb7.up.railway.app

## Authentication

All API endpoints use Bearer token auth with API keys:
```
Authorization: Bearer sk_live_xxxxxxxxxxxxx
```

## Core Endpoints

### Stage an Image
POST /api/v1/stage (1 credit)
- image: file (required) — room photo (PNG/JPG/WEBP)
- style: string — modern|traditional|contemporary|rustic|industrial|scandinavian|farmhouse|transitional|eclectic_glamour
- room_type: string — optional override (living_room|bedroom|kitchen|bathroom|dining_room|home_office|nursery|hallway|outdoor)
- product_placement: string — "true"|"false" (default: true, free)
- enhance_output: string — "true"|"false" (default: false, costs 1 extra credit)

### Enhance to 4K
POST /api/v1/enhance (1 credit)
- image: file (required)
- preset: string — default|subtle|dramatic

### Product Placement
POST /api/v1/place-products (free)
- image: file (required) — pre-staged image
- room_type: string — living_room|bedroom|kitchen|etc.

### Check Credits
GET /api/v1/credits

## Response Format

All responses are JSON. Success:
```json
{
  "success": true,
  "image_url": "https://...",
  "image_id": 4521,
  "claim_code": "SS-7X9K2M",
  "credits_used": 1,
  "credits_remaining": 9,
  "room_type": "living_room",
  "style": "modern"
}
```

Error:
```json
{
  "error": "Insufficient credits",
  "credits_required": 1,
  "credits_available": 0
}
```

## Full Documentation

- OpenAPI spec: /docs/openapi.yaml
- Full reference: /llms-full.txt
- Interactive docs: https://docs.stagingspaces.app