🏠 Interior Redesign API

🔗 API Endpoints

Complete reference for integrating with the Interior Redesign API. Each endpoint includes examples for cURL, JavaScript, and Bubble.

GET /health

Description: Check service health and authentication status

Authentication: None required

Purpose: Use this endpoint to verify the service is running and properly configured before making other API calls.

📋 cURL Example

curl -X GET "https://your-api-domain.com/health"

📤 Response (200 OK)

{ "ok": true, // Service is healthy and configured "auth_required": true // Indicates if API keys are required }

🌐 JavaScript/Bubble Example

fetch('https://your-api-domain.com/health') .then(response => response.json()) .then(data => { console.log('API Status:', data.ok); console.log('Auth Required:', data.auth_required); })
POST /v1/redesign

Description: Create a new interior redesign job

Authentication: Bearer token required

Purpose: Submit a room image and style prompt to generate AI-powered interior design suggestions.

🔑 Required Headers

Authorization: Bearer YOUR_API_KEY Content-Type: application/json

📥 Minimal Request Body

{ "image_url": "https://example.com/room.jpg", // REQUIRED: Public URL to room image "prompt": "modern minimalist living room" // REQUIRED: Style description }

📥 Complete Request Body (All Options)

{ "image_url": "https://example.com/room.jpg", "prompt": "modern minimalist living room", "preserve_layout": true, // Keep original room structure (default: true) "num_outputs": 1, // Number of variations: 1-4 (default: 1) "output_format": "png", // Format: png, jpg, jpeg, webp (default: png) "use_webhook": true, // Enable webhook notifications (default: true) "wait_seconds": 0, // Wait time for immediate response: 0-60 (default: 0) "extra": {} // Additional model parameters (optional) }

📋 cURL Example

curl -X POST "https://your-api-domain.com/v1/redesign" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image_url": "https://example.com/room.jpg", "prompt": "modern minimalist living room", "num_outputs": 2 }'

📤 Response (200 OK)

{ "job_id": "abc123-def456-ghi789", // Use this ID to check status "status": "starting" // Job status: starting → processing → succeeded/failed }

💬 Bubble Workflow Setup

API Call: POST to https://your-api-domain.com/v1/redesign Headers: - Authorization: "Bearer " + your_api_key_custom_state - Content-Type: application/json Body: { "image_url": Input_Image_URL's value, "prompt": Input_Style_Prompt's value, "num_outputs": Dropdown_NumOutputs's value as number } Action: Store result's job_id in a custom state for status checking
POST /v1/batch-redesign

Description: Create a batch interior redesign job for multiple images (1-11 images)

Authentication: Bearer token required

Purpose: Submit up to 11 room images at once for AI-powered interior design. Each image can have its own unique style prompt, and all results are tracked under a single job ID.

🔑 Required Headers

Authorization: Bearer YOUR_API_KEY Content-Type: application/json

📥 Minimal Request Body (2 images)

{ "images": [ { "image_url": "https://example.com/living-room.jpg", "prompt": "modern minimalist living room" }, { "image_url": "https://example.com/bedroom.jpg", "prompt": "cozy scandinavian bedroom" } ] }

📥 Complete Request Body (All Options)

{ "images": [ { "image_url": "https://example.com/room1.jpg", "prompt": "modern minimalist living room", "preserve_layout": true, // Override global setting for this image "extra": {} // Additional parameters for this image }, { "image_url": "https://example.com/room2.jpg", "prompt": "cozy scandinavian bedroom" // Will use global preserve_layout setting } ], "preserve_layout": true, // Default for all images (default: true) "output_format": "png", // Format for all images: png, jpg, jpeg, webp (default: png) "use_webhook": true, // Enable webhook notifications (default: true) "wait_seconds": 0 // Wait time for immediate response: 0-60 (default: 0) }

📋 cURL Example

curl -X POST "https://your-api-domain.com/v1/batch-redesign" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "images": [ { "image_url": "https://example.com/living-room.jpg", "prompt": "modern minimalist living room" }, { "image_url": "https://example.com/bedroom.jpg", "prompt": "cozy scandinavian bedroom" }, { "image_url": "https://example.com/kitchen.jpg", "prompt": "industrial style kitchen" } ], "preserve_layout": true, "output_format": "png" }'

📤 Response (200 OK)

{ "job_id": "batch-abc123-def456-ghi789", // Single job ID for all images "status": "starting" // Job status: starting → processing → succeeded/failed }

📤 Status Response (When Complete)

{ "job_id": "batch-abc123-def456-ghi789", "status": "succeeded", "output": [ "https://replicate.delivery/.../living-room-redesign.png", // Result for image 1 "https://replicate.delivery/.../bedroom-redesign.png", // Result for image 2 "https://replicate.delivery/.../kitchen-redesign.png" // Result for image 3 ], "error": null }

💬 Bubble Workflow Setup

API Call: POST to https://your-api-domain.com/v1/batch-redesign Headers: - Authorization: "Bearer " + your_api_key_custom_state - Content-Type: application/json Body: { "images": [ { "image_url": Repeating_Group_Images's Image_URL, "prompt": Repeating_Group_Images's Style_Prompt } // ... for each image in repeating group ], "preserve_layout": Checkbox_PreserveLayout's value, "output_format": Dropdown_Format's value } Action: Store result's job_id in a custom state for status checking

📝 Batch Processing Notes

• Each image can have its own unique prompt and settings • Images are processed in parallel for faster completion • Use same /v1/jobs/{job_id} endpoint to check batch status • All images' results are returned together in the output array • Maximum 11 images per batch request • Individual image failures won't affect other images in the batch
POST /v1/upscale

Description: Create an image upscaling job using Real-ESRGAN AI

Authentication: Bearer token required

Purpose: Enhance image quality and resolution (2x, 3x, or 4x) with optional face enhancement. Perfect for improving generated interior designs.

🔑 Required Headers

Authorization: Bearer YOUR_API_KEY Content-Type: application/json

📥 Minimal Request Body

{ "image_url": "https://example.com/image.jpg" }

📥 Complete Request Body (All Options)

{ "image_url": "https://example.com/image.jpg", // Image to upscale "scale": 4, // Upscaling factor: 2, 3, or 4 (default: 4) "face_enhance": true, // Enhance faces with GFPGAN (default: false) "use_webhook": true, // Enable webhook notifications (default: true) "wait_seconds": 0 // Wait time for immediate response: 0-60 (default: 0) }

📋 cURL Example

curl -X POST "https://your-api-domain.com/v1/upscale" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image_url": "https://example.com/interior-design.jpg", "scale": 4, "face_enhance": false }'

🟨 JavaScript Example

const response = await fetch('https://your-api-domain.com/v1/upscale', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ image_url: 'https://example.com/interior-design.jpg', scale: 4, face_enhance: false }) }); const data = await response.json(); console.log('Upscale Job ID:', data.job_id);

📤 Response (200 OK)

{ "job_id": "abc123-def456-ghi789", // Use this ID to check status "status": "starting" // Job status: starting → processing → succeeded/failed }

💬 Bubble Workflow Setup

API Call: POST to https://your-api-domain.com/v1/upscale Headers: - Authorization: "Bearer " + your_api_key_custom_state - Content-Type: application/json Body: { "image_url": Input_Image_URL's value, "scale": Dropdown_Scale's value as number, "face_enhance": Checkbox_FaceEnhance's value as yes/no } Action: Store result's job_id in a custom state for status checking
POST /v1/batch-upscale

Description: Create a batch image upscaling job for multiple images (1-11 images)

Authentication: Bearer token required

Purpose: Upscale multiple images at once with the same settings. All results are tracked under a single job ID.

🔑 Required Headers

Authorization: Bearer YOUR_API_KEY Content-Type: application/json

📥 Minimal Request Body (2 images)

{ "image_urls": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg" ] }

📥 Complete Request Body (All Options)

{ "image_urls": [ "https://example.com/image1.jpg", "https://example.com/image2.jpg", "https://example.com/image3.jpg" ], "scale": 4, // Upscaling factor for all images: 2, 3, or 4 (default: 4) "face_enhance": false, // Enhance faces for all images (default: false) "use_webhook": true, // Enable webhook notifications (default: true) "wait_seconds": 0 // Wait time for immediate response: 0-60 (default: 0) }

📋 cURL Example

curl -X POST "https://your-api-domain.com/v1/batch-upscale" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image_urls": [ "https://example.com/design1.jpg", "https://example.com/design2.jpg" ], "scale": 4 }'

🟨 JavaScript Example

const response = await fetch('https://your-api-domain.com/v1/batch-upscale', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ image_urls: [ 'https://example.com/design1.jpg', 'https://example.com/design2.jpg' ], scale: 4, face_enhance: false }) }); const data = await response.json(); console.log('Batch Upscale Job ID:', data.job_id);

📤 Response (200 OK)

{ "job_id": "abc123-def456-ghi789", // Use this ID to check status "status": "starting" // Job status: starting → processing → succeeded/failed }

💬 Bubble Workflow Setup

API Call: POST to https://your-api-domain.com/v1/batch-upscale Headers: - Authorization: "Bearer " + your_api_key_custom_state - Content-Type: application/json Body: { "image_urls": [List_of_Image_URLs], "scale": Dropdown_Scale's value as number, "face_enhance": Checkbox_FaceEnhance's value as yes/no } Action: Store result's job_id in a custom state for status checking
GET /v1/jobs/{job_id}

Description: Get job status and results

Authentication: Bearer token required

Purpose: Check the progress of your redesign job and retrieve results when complete. Poll this endpoint every few seconds until status changes to "succeeded" or "failed".

🔢 URL Parameters

job_id: The job ID returned from POST /v1/redesign

📋 cURL Example

curl -X GET "https://your-api-domain.com/v1/jobs/abc123-def456-ghi789" \ -H "Authorization: Bearer YOUR_API_KEY"

📤 Response (Processing)

{ "job_id": "abc123-def456-ghi789", "status": "processing", // Status: starting → processing → succeeded/failed/canceled "output": null, // Will contain image URLs when succeeded "error": null // Will contain error message if failed }

📤 Response (Completed Successfully)

{ "job_id": "abc123-def456-ghi789", "status": "succeeded", "output": [ "https://replicate.delivery/.../redesign1.png", "https://replicate.delivery/.../redesign2.png" ], "error": null }

📤 Response (Failed)

{ "job_id": "abc123-def456-ghi789", "status": "failed", "output": null, "error": "Invalid image format or URL not accessible" }

💬 Bubble Workflow (Polling)

API Call: GET to https://your-api-domain.com/v1/jobs/ + stored_job_id Headers: Authorization: "Bearer " + your_api_key_custom_state Workflow Logic: - Schedule workflow to repeat every 3 seconds - Condition: Only when status ≠ "succeeded" and ≠ "failed" - When status = "succeeded": Display output images, stop polling - When status = "failed": Show error message, stop polling
GET /v1/jobs/{job_id}/result

Description: Get job result (only for completed jobs)

Authentication: Bearer token required

Purpose: Simplified endpoint to get only the final images from a successful job. Use this instead of the status endpoint when you only need the results.

📋 cURL Example

curl -X GET "https://your-api-domain.com/v1/jobs/abc123-def456-ghi789/result" \ -H "Authorization: Bearer YOUR_API_KEY"

📤 Response (Success)

{ "job_id": "abc123-def456-ghi789", "output": [ "https://replicate.delivery/.../redesign1.png", "https://replicate.delivery/.../redesign2.png" ] }

❌ Error Responses

409 Conflict: Job not completed successfully 404 Not Found: Job ID doesn't exist 401 Unauthorized: Invalid API key
POST /v1/jobs/{job_id}/cancel

Description: Cancel a running job

Authentication: Bearer token required

Purpose: Stop a job that's taking too long or no longer needed. This will cancel the job on Replicate and update the local status.

📋 cURL Example

curl -X POST "https://your-api-domain.com/v1/jobs/abc123-def456-ghi789/cancel" \ -H "Authorization: Bearer YOUR_API_KEY"

📤 Response

{ "message": "Job cancelled successfully" }
GET /v1/jobs

Description: List all jobs with pagination

Authentication: Bearer token required

Purpose: View all your submitted jobs and their current status. Useful for building job history interfaces.

🔢 Query Parameters (Optional)

limit: Number of jobs to return (1-1000, default: 100) offset: Number of jobs to skip for pagination (default: 0) cursor: Replicate pagination cursor for external API pagination

📋 cURL Example

curl -X GET "https://your-api-domain.com/v1/jobs?limit=10&offset=0" \ -H "Authorization: Bearer YOUR_API_KEY"

📤 Response

{ "results": [ { "job_id": "abc123-def456-ghi789", "replicate_id": "replicate-prediction-id", "status": "succeeded", "created_at": "2024-01-01T12:00:00.000Z", "updated_at": "2024-01-01T12:02:30.000Z" }, { "job_id": "xyz789-uvw456-rst123", "replicate_id": "another-prediction-id", "status": "processing", "created_at": "2024-01-01T11:55:00.000Z", "updated_at": "2024-01-01T11:55:30.000Z" } ] }

🚨 Error Handling

HTTP Status Codes

200 OK: Request successful 400 Bad Request: Invalid request data 401 Unauthorized: Invalid or missing API key 404 Not Found: Resource not found (job ID, endpoint) 409 Conflict: Resource not in expected state 422 Unprocessable Entity: Validation errors 502 Bad Gateway: External service error (Replicate API) 503 Service Unavailable: Service not configured properly

Error Response Format

{ "detail": "Human-readable error description", "error_code": "optional_machine_readable_code" }

🔑 Authentication Quick Guide

All endpoints except /health require Bearer token authentication in the Authorization header.

Header Format

Authorization: Bearer YOUR_API_KEY_HERE

Getting API Keys

1. Use the Admin Panel tab to create API keys 2. Provide the admin key (ADMIN_KEY environment variable) 3. Generate a new API key with custom name and length 4. Copy the generated key and use it in Authorization headers 5. Store the key securely - it won't be shown again

🔄 Integration Workflow

Step-by-Step Process

1. Health Check: GET /health (verify service is running) 2. Create Job: POST /v1/redesign (submit image and prompt) 3. Store Job ID: Save the returned job_id for tracking 4. Poll Status: GET /v1/jobs/{job_id} every 2-5 seconds 5. Check Status: Continue polling until status ≠ "processing" 6. Handle Results: - If "succeeded": Display output images - If "failed": Show error message to user 7. Optional: Use GET /v1/jobs/{job_id}/result for final images only

Performance Tips

• Use webhooks (use_webhook: true) for real-time updates if possible • Poll status every 3-5 seconds (not faster) to avoid rate limits • Implement exponential backoff for polling intervals • Cache API keys securely, don't request them repeatedly • Handle network errors gracefully with retry logic • Set reasonable timeouts (jobs typically complete in 30-120 seconds)

API Testing

🔑 API Key

💡 Enter your API key to test authenticated endpoints

POST /v1/redesign
POST /v1/batch-redesign

🏠 Batch Image Processing (1-11 images)

Add multiple images with individual prompts. Click "Add Image" to add more (max 11).

Image 1
POST /v1/upscale

🔍 Image Upscaling (Single Image)

Enhance image quality and resolution using Real-ESRGAN AI.

POST /v1/batch-upscale

🔍 Batch Image Upscaling (1-11 images)

Upscale multiple images with the same settings. Click "Add URL" to add more (max 11).

Image 1
GET /v1/jobs/{job_id}

Admin Panel

🔐 Admin Authentication

🔑 Create New API Key

📋 API Keys Management

📊 Service Statistics

Authentication Guide

🔐 How Authentication Works

This API uses Bearer token authentication for all endpoints except the health check.

Getting an API Key:

  1. Ask your administrator for an admin key
  2. Use the Admin Panel to create API keys
  3. Each API key has a unique name and identifier

Using Your API Key:

Include the API key in the Authorization header of your requests:

Authorization: Bearer YOUR_API_KEY_HERE

Example with curl:

curl -X POST "https://your-api.com/v1/redesign" \ -H "Authorization: Bearer peSE8YgCXR-YwD9raKIt0n8ol3sRUBzB" \ -H "Content-Type: application/json" \ -d '{ "image_url": "https://example.com/room.jpg", "prompt": "modern minimalist living room" }'

Example with JavaScript fetch:

const response = await fetch('/v1/redesign', { method: 'POST', headers: { 'Authorization': 'Bearer YOUR_API_KEY_HERE', 'Content-Type': 'application/json' }, body: JSON.stringify({ image_url: 'https://example.com/room.jpg', prompt: 'modern minimalist living room' }) });

🔒 Security Best Practices

  • Never expose API keys in client-side code
  • Store API keys securely in environment variables
  • Rotate API keys regularly
  • Use different API keys for different environments
  • Monitor API key usage through admin stats