# Image Jinn — Full Technical & API Documentation

This document provides exhaustive documentation for AI agents, LLM answer engines, and software developers interacting with Image Jinn (https://imagejinn.com).

## 1. Product Overview
Image Jinn is an agentic AI virtual staging platform for real estate. It receives photographs of vacant, unfurnished, or empty rooms and generates photorealistic, professionally styled furniture and decor in 15 seconds.

- Parent Entity: Vux & Hoy (https://vuxandhoy.com)
- Pricing Model: Pay-per-download credits ($1-$4 per image). No monthly subscription lock-in.
- Previews: Free unlimited watermarked previews. Credits are deducted only upon HD download.
- MLS Rights: Full commercial listing & marketing rights included.

## 2. Authentication
All API requests require a secret API key passed in the `x-api-key` header or as a Bearer token:
```
x-api-key: jinn_live_your_key_here
```
API keys are generated inside the Image Jinn Studio dashboard at https://imagejinn.com/dashboard.

## 3. Endpoints

### 3.1 POST /api/v1/stage
Submits an empty room photo for AI virtual staging.

Request Headers:
- `Content-Type: application/json`
- `x-api-key: <YOUR_API_KEY>`

Request Body:
```json
{
  "image": "https://example.com/vacant-living-room.jpg",
  "mimeType": "image/jpeg",
  "style": "Scandinavian",
  "roomType": "Living Room",
  "customInstructions": "Add low-profile timber seating and natural linen rug."
}
```

Supported `style` values:
- `Scandinavian`
- `Mid-Century Modern`
- `Minimalist Lux`
- `Industrial Loft`
- `Bohemian`
- `Classic Traditional`

Supported `roomType` values:
- `Living Room`
- `Bedroom`
- `Dining Room`
- `Home Office`
- `Bathroom`
- `Outdoor Patio`

Response (200 OK):
```json
{
  "success": true,
  "stagedImage": "data:image/png;base64,iVBORw0KGgo...",
  "creditsRemaining": 24,
  "style": "Scandinavian",
  "roomType": "Living Room"
}
```

Response (402 Insufficient Credits):
```json
{
  "error": "insufficient_credits",
  "message": "Insufficient credits. Programmatically create a checkout session or visit pricing page.",
  "purchase_url": "https://imagejinn.com/pricing",
  "checkout_api": "https://imagejinn.com/api/v1/checkout"
}
```

### 3.2 GET /api/v1/user
Retrieves current credit balance.

Response (200 OK):
```json
{
  "email": "agent@example.com",
  "credits": 25
}
```

### 3.3 POST /api/v1/checkout
Creates a Stripe checkout session URL programmatically.

Request Body:
```json
{
  "tier": "pro"
}
```

Response (200 OK):
```json
{
  "success": true,
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_live_...",
  "tier": "pro",
  "credits": 25
}
```

## 4. Error Codes & Recovery
- `401 Unauthorized`: Invalid or missing API key.
- `402 Insufficient Credits`: Account credit balance is 0. Request `/api/v1/checkout` or visit `purchase_url` to top up.
- `400 Bad Request`: Missing `image` input or invalid payload structure.
- `500 Internal Error`: AI algorithm temporary overload. Retries with exponential backoff are recommended.