Skip to main content

Python Examples

Installation

pip install requests

Stage an Image

import requests

API_KEY = "sk_live_xxxxxxxxxxxxx"
BASE_URL = "https://stagingspaces-production-6fb7.up.railway.app"

def stage_room(image_path, style="modern", room_type=None, enhance=False):
    """Stage a room image with AI furniture placement."""
    data = {"style": style}
    if room_type:
        data["room_type"] = room_type
    if enhance:
        data["enhance_output"] = "true"

    with open(image_path, "rb") as f:
        response = requests.post(
            f"{BASE_URL}/api/v1/stage",
            headers={"Authorization": f"Bearer {API_KEY}"},
            files={"image": f},
            data=data,
        )

    response.raise_for_status()
    return response.json()


# Basic usage
result = stage_room("empty_living_room.jpg")
print(f"Staged: {result['image_url']}")
print(f"Claim code: {result['claim_code']}")

# With options
result = stage_room(
    "empty_bedroom.jpg",
    style="scandinavian",
    room_type="bedroom",
    enhance=True
)

Check Credits

def check_credits():
    response = requests.get(
        f"{BASE_URL}/api/v1/credits",
        headers={"Authorization": f"Bearer {API_KEY}"},
    )
    return response.json()

balance = check_credits()
print(f"Credits: {balance['credits']}")

Batch Stage a Property

import concurrent.futures
from pathlib import Path

def batch_stage(image_dir, style="modern", max_concurrent=5):
    """Stage all images in a directory."""
    images = sorted(Path(image_dir).glob("*.jpg"))

    # Check we have enough credits
    balance = check_credits()
    if balance["credits"] < len(images):
        print(f"Need {len(images)} credits, have {balance['credits']}")
        return []

    results = []
    with concurrent.futures.ThreadPoolExecutor(max_workers=max_concurrent) as pool:
        futures = {pool.submit(stage_room, str(img), style): img for img in images}

        for future in concurrent.futures.as_completed(futures):
            result = future.result()
            src = futures[future]
            status = "ok" if result.get("success") else "FAIL"
            print(f"[{status}] {src.name}{result.get('claim_code', 'N/A')}")
            results.append(result)

    return results

results = batch_stage("./property_123/", style="modern")

Download Staged Image

def download_staged(image_url, output_path):
    """Download a staged image to a local file."""
    response = requests.get(image_url)
    response.raise_for_status()
    with open(output_path, "wb") as f:
        f.write(response.content)
    print(f"Saved to {output_path}")

download_staged(result["image_url"], "staged_living_room.jpg")

Error Handling

def stage_with_retry(image_path, style="modern", retries=2):
    """Stage with automatic retry on transient errors."""
    for attempt in range(retries + 1):
        try:
            result = stage_room(image_path, style)
            if result.get("success"):
                return result
            if result.get("error") == "Insufficient credits":
                raise Exception("No credits remaining")
        except requests.exceptions.RequestException as e:
            if attempt == retries:
                raise
            print(f"Retry {attempt + 1}/{retries}: {e}")
    return None