# What can the API do? ## What is the AI HomeDesign API? The AI HomeDesign API lets you integrate professional real-estate photo AI directly into your own product. Send a room photo, choose a tool and some options, and receive a fully processed result image — all via simple HTTP calls. *** ### What can it do? | Category | Tools | | ------------------- | -------------------------------------------------------------------------- | | **Virtual Staging** | Add furniture to empty rooms, replace existing furniture | | **Interior Design** | Full room redesign, furniture restyle | | **Photo Editing** | Item removal, image enhancement | | **Home Renovation** | Wall, floor, ceiling, backsplash changes; under-construction visualization | | **Exterior** | Day to Dusk conversion | *** ### How does it work? Every integration follows the same four steps: ``` 1. Create a Project → groups your work by property 2. Create an Order → uploads your input image(s) 3. Create a Process → triggers the AI with your chosen tool & settings 4. Receive the result → via webhook callback or polling ``` Read the Quick Start Guide to go from zero to a processed result in minutes. *** ### Need help? Contact us at or [schedule a meeting](https://calendly.com/aihomedesign/30min). # Authentication All V3 API endpoints require an **API key** passed as an HTTP header on every request. ``` x-api-key: ``` > **Security tip:** Treat your API key like a password. Never expose it in client-side code or public repositories. If your key is compromised, regenerate it immediately. *** ### Generating an API Key The images below show how to upgrade to the Enterprise plan and generate your API key. Follow the highlighted steps to access API features and create your key successfully. Go to [AI HomeDesign Dashboard](https://app.aihomedesign.com/) and sign in to your account. Once you are on the dashboard, locate the left sidebar navigation menu and click the **Pricing** icon to view available subscription plans and upgrade to the Enterprise plan.
On the Pricing page, select the **Enterprise Plan** and complete the upgrade process to unlock API access and enable API key generation.
After completing the upgrade, a new **API** icon will appear in the left sidebar of your dashboard. Click the **API** section to access and manage your private API key.
Use your private API key in the request headers when making API calls. For security purposes, you can regenerate your private API key at any time from the **API** section of the dashboard. *** ### Using Your API Key Include the key in the `x-api-key` header on every request: ```bash curl 'https://api.aihomedesign.com/v3/project' \ --header 'x-api-key: ' ``` *** ### Common Auth Errors | Status | Meaning | What to check | | ------------------ | ---------------------------------------------- | -------------------------------------------------------------------- | | `401 Unauthorized` | API key is missing or invalid | Make sure the header is spelled `x-api-key` and the value is correct | | `403 Forbidden` | Key is valid but lacks access to this resource | Contact support — your plan may not include the requested tool | # Quick Start Guide This guide walks you through the complete flow — from first-time setup to receiving a finished AI-generated image — in the exact order you should perform each step. *** ### Step 1 — Obtain Your API Key Once you have your key, store it securely (e.g. in an environment variable — never hard-code it) and include it as `x-api-key: ` on every request. *** ### Step 2 — Register Your Webhook URL The platform will POST the result to your URL as soon as a process completes. See Webhook Reference for the full payload shape. *** ### Step 3 — Create a Project A project groups all orders for a single property. Create one project per property address. ```bash curl --location 'https://api.aihomedesign.com/v3/project' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "address": "123 Maple Street, Austin TX 78701" }' ``` **Save the `id` from the response** — this is your `project_id`. *** ### Step 4 — Upload Your Image & Create an Order Upload your image and create an order in a single multipart request. ```bash curl --location 'https://api.aihomedesign.com/v3/order' \ --header 'x-api-key: ' \ --form 'project_id=""' \ --form 'asset_file=@"/path/to/room.jpg"' ``` **Save from the response:** * `order_id` — identifies this set of input images * `assets[0].id` — the asset ID you will reference in the next step *** ### Step 5 — Create a Process Trigger the AI job by providing the order ID, the tool you want to run, and the widget configuration. ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "", "tool": "tool-virtual-staging", "asset_map": { "tool-virtual-staging-input-image": "" }, "widgets": [ { "slug": "widget-space-tool-virtual-staging", "item_slugs": ["item-bedroom-widget-space-tool-virtual-staging"] }, { "slug": "widget-style-tool-virtual-staging", "item_slugs": ["item-modern-widget-style-tool-virtual-staging"] } ] }' ``` **Response:** ```json { "process_ids": ["69a6bb11a374700bff4a1333"] } ``` **Save the `process_id`** — use it to match the incoming webhook callback. The process status begins as `pending`, moves to `processing`, and resolves to `done` or `failed`. {% hint style="info" %} Learn more about Tools and Widgets [here](/key-concepts/tools-and-widgets). {% endhint %} *** ### Step 6 — Receive the Webhook Callback Once the AI finishes, the platform POSTs the result to your registered webhook URL: ```json { "event": "process.completed", "process_id": "69a6bb11a374700bff4a1333", "order_id": "69a6aa03a374700bff4a1328", "tool": "tool-virtual-staging", "status": "done", "final_assets": [ { "asset_id": "69a6cc22a374700bff4a1400", "asset_type": "image", "temp_src": "https://cdn.aihomedesign.com/result.jpg", "temp_thumbnail_src": "https://cdn.aihomedesign.com/result_thumb.jpg" } ] } ``` Your server must respond with a `2xx` status within 10 seconds. > **Polling fallback:** If you can't use webhooks, poll `GET /v3/process/` until `status` is `done` or `failed`. Avoid polling more than once every 5 seconds. *** ### Step 7 — Download the Result The `src` field in `final_assets` is a direct download URL for the generated image: ```bash curl -o result.jpg "https://cdn.aihomedesign.com/result.jpg" ``` *** ### Flow Diagram ``` [Dashboard] Obtain API key & register webhook URL (one-time setup) [Your Server] [AI HomeDesign API] │ │ │ POST /v3/project │ │ ─────────────────────────────────────► │ Create project → save project_id │ │ │ POST /v3/order (multipart) │ │ ─────────────────────────────────────► │ Upload image → save order_id, asset_id │ │ │ POST /v3/process (JSON) │ │ ─────────────────────────────────────► │ Start AI job → save process_id │ │ │ (AI processes) │ │ │ │ POST │ │ ◄───────────────────────────────────── │ Result ready → final_assets[].src │ │ │ GET result image URL │ │ ─────────────────────────────────────► │ Download finished image ``` # Webhook Reference When a process finishes, the platform sends an HTTP `POST` request to your registered webhook URL with the result payload. This page describes the full payload shape, delivery rules, and requirements for your endpoint. *** ### Registering Your Webhook URL The images below show how to configure your webhook in the dashboard so you can automatically receive your generated photos as soon as they are ready. Click the **API** icon in the left sidebar of the dashboard. Inside the API section, you will find a **Webhook** section where you can configure your webhook URL for receiving generated photo updates.
Click the **Add Endpoint** button to create a new webhook endpoint for receiving generated photo updates.
After clicking **Add Endpoint**, enter your webhook URL and configure your preferred settings to start receiving generated photo automatically.
*** ### Payload The platform sends this JSON body when a process completes: ```json { "event": "process.completed", "process_id": "69a6bb11a374700bff4a1333", "order_id": "69a6aa03a374700bff4a1328", "tool": "tool-virtual-staging", "status": "done", "final_assets": [ { "asset_id": "69a6cc22a374700bff4a1400", "asset_type": "image", "temp_src": "https://cdn.aihomedesign.com/result.jpg", "temp_thumbnail_src": "https://cdn.aihomedesign.com/result_thumb.jpg" } ] } ``` #### Payload fields | Field | Type | Description | | ----------------------------------- | ------ | ---------------------------------------------------------------------- | | `event` | string | Always `process.completed` | | `process_id` | string | ID of the completed process — matches what `POST /v3/process` returned | | `order_id` | string | ID of the order this process belongs to | | `tool` | string | Tool slug that was run (e.g. `tool-virtual-staging`) | | `status` | string | `done` on success, `failed` on error | | `final_assets` | array | The output images (empty on failure) | | `final_assets[].asset_id` | string | Unique ID of the output asset | | `final_assets[].asset_type` | string | Always `image` for generated results | | `final_assets[].temp_src` | string | Direct URL to the full-resolution output image | | `final_assets[].temp_thumbnail_src` | string | Direct URL to a smaller thumbnail | *** ### Requirements for Your Endpoint | Requirement | Detail | | ------------------- | -------------------------------------------------------------------- | | **HTTPS** | Your webhook URL must use `https://` | | **Response time** | Must return a `2xx` status code within **10 seconds** | | **Retry behaviour** | The platform retries delivery on non-`2xx` responses | | **Idempotency** | Your handler should tolerate receiving the same event more than once | *** ### Polling Fallback If you cannot expose a public webhook endpoint, you can poll instead: ```bash curl 'https://api.aihomedesign.com/v3/process/' \ --header 'x-api-key: ' ``` Check the `status` field in the response: | Status | Meaning | | ------------ | ----------------------------------------------- | | `pending` | Queued, not yet started | | `processing` | AI is running | | `done` | Finished — read `final_assets` for results | | `failed` | Something went wrong — retry or contact support | > Avoid polling more than once every **5 seconds** to prevent rate-limiting. # Projects ### What is a Project? A **Project** is a top-level container that groups all the work done on a single property. It has an address, a cover image, and aggregated counts of input and result assets. Every order must belong to a project. *** ### Create a Project ``` POST https://api.aihomedesign.com/v3/project x-api-key: Content-Type: application/json ``` | Field | Type | Required | Description | | --------- | ------ | -------- | ------------------------ | | `address` | string | ✅ | Property address or name | ```bash curl --location 'https://api.aihomedesign.com/v3/project' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "address": "123 Maple Street, Austin TX 78701" }' ``` **Response (201 Created):** ```json { "id": "6984bd700fc3c3c614c2bea5", "address": "123 Maple Street, Austin TX 78701", "cover_src": "", "input_count": 0, "result_count": 0, "bookmarked_count": 0, "default": false, "updated_at": "2025-07-05" } ``` *** ### Fetch a Single Project ``` GET https://api.aihomedesign.com/v3/project/:id x-api-key: ``` | Query param | Description | | ----------- | --------------------------------- | | `width` | Resize cover image to this width | | `height` | Resize cover image to this height | ```bash curl 'https://api.aihomedesign.com/v3/project/6984bd700fc3c3c614c2bea5' \ --header 'x-api-key: ' ``` *** ### List All Projects ``` GET https://api.aihomedesign.com/v3/project x-api-key: ``` | Query param | Default | Description | | ------------------ | ------- | ---------------------------- | | `page` | `1` | Page number | | `limit` | `10` | Results per page (max 30) | | `sort` | `desc` | `asc`, `desc`, or `modified` | | `s` | — | Free-text search on address | | `width` / `height` | — | Resize cover thumbnails | **Response:** ```json { "data": [ { "id": "6984bd700fc3c3c614c2bea5", "address": "123 Maple Street", "cover_src": "https://...", "input_count": 3, "result_count": 12, "bookmarked_count": 2, "default": false, "updated_at": "2025-07-05" } ], "pagination": { "page": 1, "limit": 10, "total_count": 24, "total_pages": 3, "previous_page": "", "next_page": "?page=2&limit=10" } } ``` *** ### Fetch Orders Inside a Project ``` GET https://api.aihomedesign.com/v3/project/:id/order x-api-key: ``` Returns all orders that belong to the specified project, including their input assets and process results. | Query param | Default | Description | | ------------------ | ------- | ---------------------------- | | `page` | `1` | Page number | | `limit` | `10` | Results per page (max 30) | | `sort` | `desc` | `asc`, `desc`, or `modified` | | `width` / `height` | — | Resize image thumbnails | ```bash curl 'https://api.aihomedesign.com/v3/project/6984bd700fc3c3c614c2bea5/order' \ --header 'x-api-key: ' ``` # Orders ### What is an Order? An **Order** bundles one or more input images together and makes them ready for AI processing. Think of it as the "job ticket" — you create it once per set of input photos, then fire as many processes against it as you want. An order has: * **Entry assets** — the original uploaded images * **Processes** — all AI jobs run against this order * **Status** — `idle` while waiting, active during processing #### Asset roles | Role | Description | | ----------------- | ------------------------------------------------------------------ | | `primary_angle` | The main photo (required; only one allowed per order) | | `secondary_angle` | An additional angle of the same space (only one allowed per order) | | `mask` | A binary mask image used by mask-based tools | *** ### Create an Order (Upload Images) ``` POST https://api.aihomedesign.com/v3/order x-api-key: Content-Type: multipart/form-data ``` | Form field | Required | Description | | ------------- | ------------ | ----------------------------------------------------------------------------------------- | | `project_id` | Optional | ID of the project to attach this order to | | `asset_file` | At least one | Image file(s) to upload — repeat for multiple files | | `asset_roles` | Optional | Role for each file — positionally aligned with `asset_files`, defaults to `primary_angle` | **Single image:** 
curl --location 'https://api.aihomedesign.com/v3/order' \
  --header 'x-api-key: <your_api_key>' \
  --form 'project_id="6984bd700fc3c3c614c2bea5"' \
  --form 'asset_file=@"/path/to/room.jpeg"'
**Two images — primary + secondary angle:** ```bash curl --location 'https://api.aihomedesign.com/v3/order' \ --header 'x-api-key: ' \ --form 'project_id="6984bd700fc3c3c614c2bea5"' \ --form 'asset_file=@"/path/to/house_front.jpeg"' \ --form 'asset_file=@"/path/to/house_side.jpeg"' \ --form 'asset_role="primary_angle"' \ --form 'asset_role="secondary_angle"' ``` **Upload Mask Image (Item Removal Mask tool)** 
curl --location 'https://api.aihomedesign.com/v3/order/:id/append' \
  --header 'x-api-key: <your_api_key>' \
  --form 'project_id="6984bd700fc3c3c614c2bea5"' \
  --form 'asset_file=@"/path/to/mask.png"' \
  --form 'asset_role="mask"' \
  --form 'asset_type="mask"' \
{% hint style="info" %} A binary mask image — blue (**#7878CD**) pixels = remove | black pixels = keep {% endhint %} **Response (201 Created):** ```json { "order_id": "69a6aa03a374700bff4a1328", "assets": [ { "id": "69a6aa03a374700bff4a1327", "src": "https://cdn.aihomedesign.com/...", "asset_type": "image", "asset_role": "primary_angle" } ] } ``` > **Save** the `order_id` and each asset `id` — you need them when creating a process. *** ### Fetch a Single Order ``` GET https://api.aihomedesign.com/v3/order/:id x-api-key: ``` Optional query params: `width`, `height` to resize image URLs. **Response:** ```json { "id": "69a6aa03a374700bff4a1328", "project_id": "6984bd700fc3c3c614c2bea5", "entry_assets": [ { "id": "69a6aa03a374700bff4a1327", "asset_type": "image", "asset_role": "primary_angle", "src": "https://cdn.aihomedesign.com/...", "thumbnail_src": "https://cdn.aihomedesign.com/.../thumb" } ], "status": "idle", "created_at": "2025-07-05T10:00:00Z", "updated_at": "2025-07-05T10:00:00Z", "processes": [ { "id": "69a6bb11a374700bff4a1333", "tool": "tool-virtual-staging", "status": "done", "final_assets": [...] } ] } ``` # Processes ### What is a Process? A **Process** is a single AI generation job. It applies one tool to the input assets of an order, configured by the widgets you select, and produces output images called **final assets**. Key facts: * Multiple processes can be created from the same order (e.g. try "Modern" style, then try "Scandinavian" — same order, two processes) * A process goes through statuses: `pending` → `processing` → `done` / `failed` * Results are delivered via webhook or available to poll *** ### Create a Process ``` POST https://api.aihomedesign.com/v3/process x-api-key: Content-Type: application/json ``` | Field | Type | Required | Description | | ------------------ | ------ | --------------- | --------------------------------------------------------- | | `order_id` | string | ✅ | The order containing the input images | | `tool` | string | ✅ | Tool slug (e.g. `tool-virtual-staging`) | | `asset_map` | object | ✅ | Maps each tool input slot to an asset ID | | `widgets` | array | Depends on tool | Widget configurations — see below | | `process_group_id` | string | Optional | Links this process to a related one (used for mask tools) | #### asset\_map Maps the tool's named input slot(s) to asset IDs from your order: ```json "asset_map": { "tool-virtual-staging-input-image": "" } ``` Input slot names follow the pattern `-input-image`. Some tools have two slots (e.g. `-input-image-before` and `-input-image-after`). See each tool's page in the Tool Reference for exact slot names. #### widgets ```json "widgets": [ { "slug": "widget-space-tool-virtual-staging", "item_slugs": ["item-bedroom-widget-space-tool-virtual-staging"] }, { "slug": "widget-style-tool-virtual-staging", "item_slugs": ["item-modern-widget-style-tool-virtual-staging"] } ] ``` * `slug` — which widget you are configuring * `item_slugs` — the selected option(s); most widgets take one item, some accept multiple **Response (201 Created):** ```json { "process_ids": ["69a6bb11a374700bff4a1333"], "process_group_id": "69a6bb11a374700bff4a1334" } ``` > `process_group_id` is only returned for tools that create a group (e.g. mask-based removal). *** ### Fetch a Process ``` GET https://api.aihomedesign.com/v3/process/:id x-api-key: ``` Optional query params: `width`, `height` to resize output image URLs. **Response:** ```json { "id": "69a6bb11a374700bff4a1333", "tool": "tool-virtual-staging", "status": "done", "final_assets": [ { "asset_id": "69a6cc22a374700bff4a1400", "asset_type": "image", "asset_role": "result", "src": "https://cdn.aihomedesign.com/result.jpg", "thumbnail_src": "https://cdn.aihomedesign.com/result_thumb.jpg" } ], "bookmarked": false, "feedback": { "type": "", "description": "" } } ``` | Status | Meaning | | ------------ | ---------------------------------------------- | | `pending` | Queued, not yet started | | `processing` | AI is running | | `done` | Finished — `final_assets` contains the results | | `failed` | Something went wrong | # Tools & Widgets Before writing a single line of code it is important to understand what **Tools** and **Widgets** are, because every API call you make is built around them. *** ### What is a Tool? A **Tool** is one of the AI services the platform offers. Think of it the same way you think of an app on your phone — each tool does one specific job, and you pick the one that matches what you want to accomplish. For example: * Want to add furniture to an empty room? → use **AI Virtual Staging** (`tool-virtual-staging`) * Want to convert a daytime exterior to a golden-hour dusk shot? → use **AI Day to Dusk** (`tool-day-to-dusk`) * Want to remove unwanted objects from a photo? → use **AI Item Removal** (`tool-item-removal`) Every tool has two identifiers: | Identifier | Example | Where it's used | | ---------- | ---------------------- | ---------------------------------- | | **Name** | `AI Virtual Staging` | Human-readable label in the UI | | **Slug** | `tool-virtual-staging` | The value you send in API requests | You always use the **slug** in your code. Each tool also defines one or more **input slots** — named placeholders for the images you upload. For example, the Virtual Staging tool has one slot called `tool-virtual-staging-input-image`. You map each slot to the ID of an asset you uploaded. Some tools (like Darkness) have two slots — a "before" and an "after" image. #### Fetching all available tools ```bash curl 'https://app.aihomedesign.com/api/tools' ``` No authentication required. Response: ```json { "data": [ { "id": "6848085cd55c9753c282ca69", "name": "AI Virtual Staging", "slug": "tool-virtual-staging", "isActive": true }, ... ] } ``` #### All available tools | Slug | Display Name | What it does | | ---------------------------- | ---------------------- | ------------------------------------------------------------- | | `tool-virtual-staging` | AI Virtual Staging | Furnishes an empty room with AI-generated furniture | | `tool-virtual-restaging` | AI Virtual Restaging | Replaces existing furniture with a new style | | `tool-item-removal` | AI Item Removal | Automatically removes objects from a room photo | | `tool-item-removal-mask` | AI Item Removal (Mask) | Removes specific items you mark with a mask image | | `tool-image-enhancement` | AI Image Enhancement | Improves lighting, sharpness, colour balance and adds effects | | `tool-interior-design` | AI Interior Designer | Fully redesigns a room with a chosen style and palette | | `tool-furniture-set-restyle` | AI Furniture Restyle | Swaps out a room's furniture set for a different style | | `tool-wall-change` | AI Wall Change | Changes wall colour, texture or wallpaper | | `tool-floor-change` | AI Floor Change | Swaps the floor material (marble, hardwood, tile, etc.) | | `tool-ceiling-change` | AI Ceiling Change | Changes the ceiling material or colour | | `tool-backsplash-change` | AI Backsplash Change | Changes the kitchen or bathroom backsplash | | `tool-under-construction` | AI Under Construction | Visualises a finished space from an unfinished room photo | | `tool-day-to-dusk` | AI Day to Dusk | Converts a daytime exterior to a dusk/twilight scene | *** ### What is a Widget? A **Widget** is a setting that tells the tool *how* to process your image. Think of it like the settings panel on a photo editing app — before the AI runs, you choose things like: * **Which room type** is in the photo? (Bedroom, Living Room, Kitchen…) * **What design style** should be applied? (Modern, Scandinavian, Bohemian…) * **What material** should the floor be changed to? (White Marble, Hardwood, Tile…) Each tool has its own set of widgets. Some widgets are **required** (you must pick an option) and some are **optional**. #### Widgets have Items Every widget contains a list of **Items** — the actual choices. For example: ``` Widget: "Space Type" (slug: widget-space-tool-virtual-staging) │ ├── Item: "Bedroom" (slug: item-bedroom-widget-space-tool-virtual-staging) ├── Item: "Living Room" (slug: item-living-room-widget-space-tool-virtual-staging) ├── Item: "Kitchen" (slug: item-kitchen-widget-space-tool-virtual-staging) └── ... ``` When you call the API you always provide both: 1. The **widget slug** — which setting you are configuring 2. One or more **item slugs** — which option(s) you are selecting Most widgets are **single-select** (one item). A few are **multi-select** — you can pass several item slugs at once (e.g. the Image Enhancement "Enhancement Options" widget). #### Understanding slug naming Slugs follow a self-describing convention: ``` Widget slug: widget - - Item slug: item - - Examples: widget-space-tool-virtual-staging item-bedroom-widget-space-tool-virtual-staging ``` *** ### How Tools and Widgets Work Together Here is the full picture for virtually staging a bedroom in modern style: ``` Tool: tool-virtual-staging asset_map: { "tool-virtual-staging-input-image": "" } widgets: [ { slug: "widget-space-tool-virtual-staging", item_slugs: ["item-bedroom-widget-space-tool-virtual-staging"] → tells the AI: "this room is a bedroom" }, { slug: "widget-style-tool-virtual-staging", item_slugs: ["item-modern-widget-style-tool-virtual-staging"] → tells the AI: "use a modern design style" } ] ``` Want a living room in Scandinavian style instead? Just swap the item slugs — nothing else changes. See the Tool Reference section for exact slugs for every tool. ### **Retrieving Available Widgets** ``` GET https://api.aihomedesign.com/v1/cathub/tools/{tool_slug}/widgets x-api-key: Content-Type: application/json ``` #### Response Structure Sample Response: ``` { "data": [ { "id": "687e16b50d64078bca02b614", "slug": "widget-enhancement-options-tool-image-enhancement", "name": "Enhancement Options", "description": "", "isOptional": true, "isActive": true, "priority": 10, "type": "toggle", "tool": "tool-image-enhancement", "items": [ { "slug": "item-lawn-replacement-widget-enhancement-options-tool-image-enhancement", "name": "Lawn Replacement", "description": "", "prompt": "replace lawn", "priority": 1, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/rdl-stage-cathub/79097eb9-46bc-4233-9399-2dbccccbf9de.svg", "accessibleIn": [ "item-outdoor-widget-area-tool-image-enhancement" ] }, { "slug": "item-sky-replacement-widget-enhancement-options-tool-image-enhancement", "name": "Sky Replacement", "description": "", "prompt": "sky replacement", "priority": 2, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/aihomedesign/widget-item/2441d7ac-3d7f-4819-9d6f-dfb11659aa72.svg", "accessibleIn": [ "item-outdoor-widget-area-tool-image-enhancement" ] }, { "slug": "item-add-fire-to-fireplace-widget-enhancement-options-tool-image-enhancement", "name": "Add Fire to Fireplace", "description": "", "prompt": "add fire to fire place", "priority": 3, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/aihomedesign/widget-item/9f50436d-17ea-40d9-9aa7-0355d0c07a01.webp", "accessibleIn": [ "item-indoor-widget-area-tool-image-enhancement", "item-outdoor-widget-area-tool-image-enhancement" ] }, { "slug": "item-add-screen-to-tv-widget-enhancement-options-tool-image-enhancement", "name": "Add Screen to TV", "description": "", "prompt": "add screen to tv", "priority": 4, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/aihomedesign/widget-item/06571c7f-8fc4-4606-bfd5-e73c9a6a0c8d.png", "accessibleIn": [ "item-indoor-widget-area-tool-image-enhancement" ] }, { "slug": "item-remove-extra-objects-widget-enhancement-options-tool-image-enhancement", "name": "Remove Extra Objects", "description": "", "prompt": "delete extra object", "priority": 5, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/rdl-stage-cathub/f10d109f-9375-4c3e-a459-56e17b121174.svg", "accessibleIn": [ "item-indoor-widget-area-tool-image-enhancement", "item-outdoor-widget-area-tool-image-enhancement" ] }, { "slug": "item-remove-minor-blemishes-widget-enhancement-options-tool-image-enhancement", "name": "Remove Minor Blemishes", "description": "", "prompt": "remove small blemish", "priority": 6, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/rdl-stage-cathub/059da4c6-dd1d-4077-94e1-3a99a52597cb.svg", "accessibleIn": [ "item-indoor-widget-area-tool-image-enhancement", "item-outdoor-widget-area-tool-image-enhancement" ] }, { "slug": "item-turn-on-the-light-widget-enhancement-options-tool-image-enhancement", "name": "Turn On the Light", "description": "", "prompt": "turn on the lights inside", "priority": 7, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/rdl-stage-cathub/e83d1a23-28ed-4495-9804-40785ddab368.svg", "accessibleIn": [ "item-indoor-widget-area-tool-image-enhancement", "item-outdoor-widget-area-tool-image-enhancement" ] } ], "related": [ "widget-area-tool-image-enhancement" ], "key": "enhancement_options", "createdAt": "2025-01-21T12:09:02.164Z", "updatedAt": "2025-12-17T07:38:36.341Z" }, { "id": "687e132a0d64078bca02b612", "slug": "widget-area-tool-image-enhancement", "name": "Area", "description": "", "isOptional": false, "isActive": true, "priority": 10, "type": "tile", "tool": "tool-image-enhancement", "items": [ { "slug": "item-indoor-widget-area-tool-image-enhancement", "name": "Indoor", "description": "", "prompt": "interior photo enhancement", "priority": 0, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/aihomedesign/space/d00ace4d-68df-4581-87d7-fd370c1a41e6.svg", "accessibleIn": null }, { "slug": "item-outdoor-widget-area-tool-image-enhancement", "name": "Outdoor", "description": "", "prompt": "outdoor photo enhancement", "priority": 10, "isActive": true, "isDefault": false, "iconSrc": "https://s3.amazonaws.com:443/aihomedesign/space/cbb0c9f2-632a-495d-9fda-690b3c2b6421.svg", "accessibleIn": null } ], "related": null, "key": "space", "createdAt": "2025-01-21T12:09:02.164Z", "updatedAt": "2025-01-21T12:09:02.164Z" } ], "message": "" } ``` *** #### Widget Each widget object contains the following fields: | slug | Unique widget identifier. | | ---------- | --------------------------------------------------------------------------- | | name | Human-readable widget name. | | type | Widget type (`tile`, `toggle`, etc.). | | key | Parameter key used when submitting widget selections in a process request. | | isOptional | Indicates whether selection is required. | | items | Available options for the widget. | | related | List of widgets that control the visibility or availability of this widget. | #### Widget Items Each widget contains one or more items representing selectable options. | Field | Description | | ------------ | ---------------------------------------------------------------- | | slug | Unique item identifier. | | name | Display name shown to users. | | prompt | Internal prompt associated with the option. | | iconSrc | URL of the item's icon. | | isDefault | Indicates whether the item is selected by default. | | accessibleIn | Restricts availability to specific selections in another widget. | #### Conditional Availability Some widget items are only available when specific options are selected in another widget. For example, in the Image Enhancement tool: * **Lawn Replacement** is only available when **Outdoor** is selected. * **Add Screen to TV** is only available when **Indoor** is selected. * **Add Fire to Fireplace** is available for both **Indoor** and **Outdoor**. This relationship is defined through the `accessibleIn` field. ``` { "name": "Lawn Replacement", "accessibleIn": [ "item-outdoor-widget-area-tool-image-enhancement" ] } ``` # Error Codes All API errors return a JSON body with an `error` field describing what went wrong. ```json { "error": "...", "key": "api_error_..." } ``` *** ### HTTP Status Codes | Status | Name | Common causes | | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------- | | `400` | Bad Request | Missing required field; invalid value for an enum field; wrong asset role | | `401` | Unauthorized | `x-api-key` header is missing or the key is invalid | | `403` | Forbidden | API key is valid but your plan does not include access to this tool or endpoint | | `404` | Not Found | The order, process, project, or asset ID does not exist | | `422` | Unprocessable Entity | `asset_map` key does not match the tool's input spec; widget slug is invalid; item slug does not belong to the widget | *** ### Debugging Tips **401 on every request** * Check that the header name is exactly `x-api-key` (all lowercase) * Check that the value is the full key with no extra spaces **403 on a specific tool** * Your plan may not include that tool — contact **422 on process creation** * Double-check that the `asset_map` key matches the tool's input slot slug exactly (e.g. `tool-virtual-staging-input-image`) * Double-check that each widget slug and item slug are correct for the tool you are using — see the Tool Reference **Process stuck in `pending` or `processing`** * Wait a few minutes — complex tools take longer * If it stays `failed`, retry the process or contact support with the `process_id` # Migrating from V1 V3 replaces the V1 API entirely. This page maps every V1 concept and endpoint to its V3 equivalent so you can migrate without guessing. *** ### Concept Mapping | V1 | V3 | Notes | | -------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------- | | `service_name` (e.g. `service-ai-virtual-staging`) | `tool` slug (e.g. `tool-virtual-staging`) | Same idea, new naming scheme | | `space_name` (e.g. `space-bedroom`) | Widget item slug (e.g. `item-bedroom-widget-space-tool-virtual-staging`) | Now part of the `widgets` array | | Widget IDs (numeric) | Widget & item slugs (string) | Slugs are human-readable and self-describing | | No project concept | `POST /v3/project` | Orders must now belong to a project | *** ### Endpoint Mapping | V1 endpoint | V3 equivalent | Key difference | | ---------------------- | ------------------- | ---------------------------------------------------------------------------------- | | `POST /v1/order/image` | `POST /v3/order` | Upload + order creation are now one call; returns `order_id` **and** `assets[].id` | | `POST /v1/order` | `POST /v3/process` | The "submit order" step is now called "create process" | | `GET /v1/order/:id` | `GET /v3/order/:id` | Response includes full `processes` array with results | *** ### Migration Steps 1. **Create a project** for each property you work with (`POST /v3/project`) — there is no V1 equivalent. 2. **Replace your image upload call** — instead of `POST /v1/order/image`, use `POST /v3/order` (multipart). It returns both `order_id` and asset IDs in one response. 3. **Replace your order submission call** — instead of `POST /v1/order` with `service_name` and `space_name`, use `POST /v3/process` with: * `tool` (slug) * `asset_map` (maps input slot slug → asset ID) * `widgets` (array of `{ slug, item_slugs }`) 4. **Update your webhook handler** — the V3 payload shape is richer; check Webhook Reference for the exact fields. *** ### Example: V1 vs V3 Side by Side **V1 — upload image:** ```bash curl --location 'https://api.aihomedesign.com/v1/order/image' \ --header 'x-api-key: ' \ --form 'image=@"/path/to/room.jpg"' \ --form 'service_name="service-ai-virtual-staging"' # → returns { "order_id": "..." } ``` **V3 — create order:** ```bash curl --location 'https://api.aihomedesign.com/v3/order' \ --header 'x-api-key: ' \ --form 'project_id=""' \ --form 'asset_file=@"/path/to/room.jpg"' # → returns { "order_id": "...", "assets": [{ "id": "...", ... }] } ``` **V1 — submit order:** ```bash curl --location 'https://api.aihomedesign.com/v1/order' \ --header 'x-api-key: ' \ --data '{ "order_id": "...", "service_name": "service-ai-virtual-staging", "space_name": "space-bedroom", "widget_ids": [12, 34] }' ``` **V3 — create process:** ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --data '{ "order_id": "...", "tool": "tool-virtual-staging", "asset_map": { "tool-virtual-staging-input-image": "" }, "widgets": [ { "slug": "widget-space-tool-virtual-staging", "item_slugs": ["item-bedroom-widget-space-tool-virtual-staging"] }, { "slug": "widget-style-tool-virtual-staging", "item_slugs": ["item-modern-widget-style-tool-virtual-staging"] } ] }' ``` # Postman Collection Postman Workspace for APIs This Postman collection provides a convenient way to explore and interact with our APIs locally. By downloading and importing the collection into Postman, developers can quickly access all available endpoints, along with predefined request structures and example calls. The collection includes organized folders, detailed request configurations, and sample payloads to help you understand how each endpoint works. It is designed to simplify testing, accelerate integration, and provide a hands-on way to experiment with the API. We recommend using this collection as a starting point for development and testing. Feel free to customize requests, environments, and variables to match your specific use case. {% file src="/files/nK4YcR6mFuXLX4IaYzpb" %} # AI Backsplash Change Virtually changes the kitchen or bathroom backsplash material — tile, marble, mosaic, and more. *** ### Input Slots | Slot key | Description | | ------------------------------------ | ----------------------------- | | `tool-backsplash-change-input-image` | The kitchen or bathroom photo | ### Widgets | Widget slug | Purpose | Select | | ---------------------------------------- | ------------------------------ | ------ | | `widget-space-tool-backsplash-change` | Room type (Kitchen, Bathroom…) | Single | | `widget-material-tool-backsplash-change` | Backsplash material | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-backsplash-change", "asset_map": { "tool-backsplash-change-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-space-tool-backsplash-change", "item_slugs": ["item-kitchen-widget-space-tool-backsplash-change"] }, { "slug": "widget-material-tool-backsplash-change", "item_slugs": ["item-grey-marble-widget-material-tool-backsplash-change"] } ] }' ``` # AI Ceiling Change Virtually changes the ceiling material, colour, or texture in a room photo. *** ### Input Slots | Slot key | Description | | --------------------------------- | -------------- | | `tool-ceiling-change-input-image` | The room photo | ### Widgets | Widget slug | Purpose | Select | | ------------------------------------- | ---------------- | ------ | | `widget-space-tool-ceiling-change` | Room type | Single | | `widget-material-tool-ceiling-change` | Ceiling material | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-ceiling-change", "asset_map": { "tool-ceiling-change-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-space-tool-ceiling-change", "item_slugs": ["item-bedroom-widget-space-tool-ceiling-change"] }, { "slug": "widget-material-tool-ceiling-change", "item_slugs": ["item-wooden-ceiling-widget-material-tool-ceiling-change"] } ] }' ``` # AI Day to Dusk Converts a daytime exterior photo into a dramatic dusk or twilight scene. You can choose the sky style and optionally apply shadow removal or lawn touch-up. *** ### Input Slots | Slot key | Description | | ------------------------------ | -------------------------- | | `tool-day-to-dusk-input-image` | The daytime exterior photo | ### Widgets | Widget slug | Purpose | Select | | --------------------------------------------- | ---------------------------------------------- | --------- | | `widget-sky-style-tool-day-to-dusk` | Sky / lighting mood | Single | | `widget-day-to-dusk-options-tool-day-to-dusk` | Optional edits (shadow removal, lawn touch-up) | **Multi** | > `widget-day-to-dusk-options-tool-day-to-dusk` is **multi-select** — you can combine multiple optional effects. ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-day-to-dusk", "asset_map": { "tool-day-to-dusk-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-sky-style-tool-day-to-dusk", "item_slugs": ["item-twilight-with-cloud-widget-sky-style-tool-day-to-dusk"] }, { "slug": "widget-day-to-dusk-options-tool-day-to-dusk", "item_slugs": [ "item-shadow-removal-widget-day-to-dusk-options-tool-day-to-dusk", "item-lawn-touch-up-widget-day-to-dusk-options-tool-day-to-dusk" ] } ] }' ``` # AI Floor Change Virtually swaps the floor material — hardwood, marble, tile, carpet, and more. *** ### Input Slots | Slot key | Description | | ------------------------------- | -------------- | | `tool-floor-change-input-image` | The room photo | ### Widgets | Widget slug | Purpose | Select | | ----------------------------------- | -------------- | ------ | | `widget-space-tool-floor-change` | Room type | Single | | `widget-material-tool-floor-change` | Floor material | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-floor-change", "asset_map": { "tool-floor-change-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-space-tool-floor-change", "item_slugs": ["item-bedroom-widget-space-tool-floor-change"] }, { "slug": "widget-material-tool-floor-change", "item_slugs": ["item-white-marble-widget-material-tool-floor-change"] } ] }' ``` # AI Furniture Restyle Replaces the full furniture set in a room with a different style, while keeping the room structure (walls, floors, ceiling) unchanged. *** ### Input Slots | Slot key | Description | | ------------------------------------ | ------------------------- | | `tool-furniture-restyle-input-image` | The room photo to restyle | ### Widgets | Widget slug | Purpose | Select | | ------------------------------------- | ------------ | ------ | | `widget-space-tool-furniture-restyle` | Room type | Single | | `widget-style-tool-furniture-restyle` | Design style | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-furniture-restyle", "asset_map": { "tool-furniture-restyle-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-space-tool-furniture-restyle", "item_slugs": ["item-bedroom-widget-space-tool-furniture-restyle"] }, { "slug": "widget-style-tool-furniture-restyle", "item_slugs": ["item-modern-widget-style-tool-furniture-restyle"] } ] }' ``` # AI Image Enhancement Improves the overall quality of a room photo: corrects lighting, sharpens details, balances colours, and can add optional enhancement effects like fire in a fireplace or a screen on a TV. *** ### Input Slots | Slot key | Description | | ------------------------------------ | -------------------- | | `tool-image-enhancement-input-image` | The photo to enhance | ### Widgets | Widget slug | Purpose | Select | | --------------------------------------------------- | ------------------------------------- | --------- | | `widget-area-tool-image-enhancement` | Area type — indoor or outdoor | Single | | `widget-enhancement-options-tool-image-enhancement` | Optional enhancement effects to apply | **Multi** | #### Enhancement Options widget items (examples) | Item slug | Effect | | ------------------------------------------------------------------------------ | ----------------------------------------- | | `item-add-fire-to-fireplace-widget-enhancement-options-tool-image-enhancement` | Adds realistic fire to an empty fireplace | | `item-add-screen-to-tv-widget-enhancement-options-tool-image-enhancement` | Adds a screen image to a blank TV | > This widget is **multi-select** — you can pass multiple item slugs at once. ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-image-enhancement", "asset_map": { "tool-image-enhancement-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-area-tool-image-enhancement", "item_slugs": ["item-indoor-widget-area-tool-image-enhancement"] }, { "slug": "widget-enhancement-options-tool-image-enhancement", "item_slugs": [ "item-add-fire-to-fireplace-widget-enhancement-options-tool-image-enhancement", "item-add-screen-to-tv-widget-enhancement-options-tool-image-enhancement" ] } ] }' ``` # AI Interior Designer Fully redesigns a room by replacing walls, floors, furniture, and décor according to your chosen style and colour palette. *** ### Input Slots | Slot key | Description | | ---------------------------------- | -------------------------- | | `tool-interior-design-input-image` | The room photo to redesign | ### Widgets | Widget slug | Purpose | Select | | ----------------------------------- | -------------- | ------ | | `widget-space-tool-interior-design` | Room type | Single | | `widget-style-tool-interior-design` | Design style | Single | | `widget-color-tool-interior-design` | Colour palette | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6936dc8b2bddf58d9e8137bd", "tool": "tool-interior-design", "asset_map": { "tool-interior-design-input-image": "6936dc8a2bddf58d9e8137bc" }, "widgets": [ { "slug": "widget-space-tool-interior-design", "item_slugs": ["item-bedroom-widget-space-tool-interior-design"] }, { "slug": "widget-style-tool-interior-design", "item_slugs": ["item-modern-widget-style-tool-interior-design"] }, { "slug": "widget-color-tool-interior-design", "item_slugs": ["item-earthy-neutrals-widget-color-tool-interior-design"] } ] }' ``` # AI Item Removal (Mask) Removes specific items from a photo using a binary mask image you provide. White areas in the mask are removed; black areas are kept. Use this when you need precise control over which objects are removed. *** ### Input Slots | Slot key | Description | | ------------------------------------ | ----------------------------------------------------------------------------- | | `tool-item-removal-mask-input-image` | The original room photo | | `tool-item-removal-mask-input-mask` | A binary mask image — blue (**#7878CD**) pixels = remove, black pixels = keep | ### Widgets No widgets required. ### Optional Field | Field | Description | | ------------------ | --------------------------------------------------------------------------- | | `process_group_id` | Link this process to a preceding auto-detect process (from AI Item Removal) | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "694002a7bae1a7c81627e3cf", "tool": "tool-item-removal-mask", "process_group_id": "694002f74da0895282fbdb85", "asset_map": { "tool-item-removal-mask-input-image": "694002f74da0895282fbdb87", "tool-item-removal-mask-input-mask": "694003b24da0895282fbdb89" } }' ``` > **Tip:** Upload the mask image to the same order using `POST /v3/order/:id/append` before creating this process. see complete request format [here](/key-concepts/orders#create-an-order-upload-images). # AI Item Removal Automatically detects and removes furniture and unwanted objects from a room photo, leaving a clean empty space. *** ### Input Slots | Slot key | Description | | ------------------------------- | ----------------------------------- | | `tool-item-removal-input-image` | The room photo to remove items from | ### Widgets No widgets required — the AI automatically detects what to remove. ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "699c61b30d551c99bc109663", "tool": "tool-item-removal", "asset_map": { "tool-item-removal-input-image": "699c61b30d551c99bc109662" }, "widgets": [] }' ``` > **Need to remove specific items?** Use AI Item Removal (Mask) to draw a mask over exactly what you want removed. # AI Under Construction Visualises what an unfinished or under-construction space will look like when complete, based on your chosen room type and design style. *** ### Input Slots | Slot key | Description | | ------------------------------------- | ------------------------- | | `tool-under-construction-input-image` | The unfinished room photo | ### Widgets | Widget slug | Purpose | Select | | -------------------------------------- | ---------------- | ------ | | `widget-space-tool-under-construction` | Target room type | Single | | `widget-style-tool-under-construction` | Design style | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-under-construction", "asset_map": { "tool-under-construction-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-space-tool-under-construction", "item_slugs": ["item-kitchen-widget-space-tool-under-construction"] }, { "slug": "widget-style-tool-under-construction", "item_slugs": ["item-contemporary-widget-style-tool-under-construction"] } ] }' ``` # AI Virtual Restaging Replaces the existing furniture in an already-staged room with a completely new style, without removing the furniture manually first. *** ### Input Slots | Slot key | Description | | ------------------------------------ | -------------------------------- | | `tool-virtual-restaging-input-image` | The staged room photo to restyle | ### Widgets | Widget slug | Purpose | Select | | ------------------------------------- | ------------ | ------ | | `widget-space-tool-virtual-restaging` | Room type | Single | | `widget-style-tool-virtual-restaging` | Design style | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-virtual-restaging", "asset_map": { "tool-virtual-restaging-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-space-tool-virtual-restaging", "item_slugs": ["item-bedroom-widget-space-tool-virtual-restaging"] }, { "slug": "widget-style-tool-virtual-restaging", "item_slugs": ["item-modern-widget-style-tool-virtual-restaging"] } ] }' ``` # AI Virtual Staging Furnishes an empty room with AI-generated furniture matching your chosen room type and design style. *** ### Input Slots | Slot key | Description | | ---------------------------------- | ----------------------------- | | `tool-virtual-staging-input-image` | The empty room photo to stage | ### Widgets | Widget slug | Purpose | Select | | ----------------------------------- | ---------------------------------------------- | ------ | | `widget-space-tool-virtual-staging` | Room type (Bedroom, Living Room, Kitchen…) | Single | | `widget-style-tool-virtual-staging` | Design style (Modern, Scandinavian, Bohemian…) | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "69a6aa03a374700bff4a1328", "tool": "tool-virtual-staging", "asset_map": { "tool-virtual-staging-input-image": "69a6aa03a374700bff4a1327" }, "widgets": [ { "slug": "widget-space-tool-virtual-staging", "item_slugs": ["item-bedroom-widget-space-tool-virtual-staging"] }, { "slug": "widget-style-tool-virtual-staging", "item_slugs": ["item-modern-widget-style-tool-virtual-staging"] } ] }' ``` ### Example Response ```json { "process_ids": ["69a6bb11a374700bff4a1333"] } ``` # AI Wall Change Virtually changes the wall colour, texture, or wallpaper in a room photo. *** ### Input Slots | Slot key | Description | | ------------------------------ | -------------- | | `tool-wall-change-input-image` | The room photo | ### Widgets | Widget slug | Purpose | Select | | ---------------------------------- | ----------------------- | ------ | | `widget-space-tool-wall-change` | Room type | Single | | `widget-material-tool-wall-change` | Wall material or finish | Single | ### Example Request ```bash curl --location 'https://api.aihomedesign.com/v3/process' \ --header 'x-api-key: ' \ --header 'Content-Type: application/json' \ --data '{ "order_id": "6878b6d52ecd619eab1f886d", "tool": "tool-wall-change", "asset_map": { "tool-wall-change-input-image": "6878b6882ecd619eab1f886c" }, "widgets": [ { "slug": "widget-space-tool-wall-change", "item_slugs": ["item-bedroom-widget-space-tool-wall-change"] }, { "slug": "widget-material-tool-wall-change", "item_slugs": ["item-brick-wall-widget-material-tool-wall-change"] } ] }' ``` # Rate Limit For fair usage To ensure fair usage and maintain the stability of our service, the following rate limit policy is enforced: ## **Order Submission Rate Limit** * Limit: Users can submit a maximum of **30 concurrent (simultaneous) orders within 10 minutes**. * Scope: The rate limit is applied per user. (Excluding regenerations) * HTTP Status Code: If a user exceeds this rate limit, they will receive a `429 Too Many Requests` response. {% hint style="info" %} If you have any issues with the current rate limit or are looking for a unique rate limit for your business operations, [feel free to schedule a meeting here](https://calendly.com/aihomedesign/30min). Also, you can send your request to . {% endhint %} ## Response ``` { "error": "rate-limit exceeded, 30 generates per 10 minutes only", } ``` ## Best Practices to Avoid Rate Limit Errors * Implement client-side rate limiting. * Handle `429` responses by pausing for the appropriate duration. # Help & Support We're here for you in each step If you have any questions or suggestions, please don't hesitate to email us at . Also, if you feel an online meeting could resolve your issue faster, [feel free to schedule a meeting here](https://calendly.com/aihomedesign/30min). # FAQs Frequently Asked Questions 1. **Do I get access to all AI HomeDesign services using this API?** By using our API, you get access to AI Interior Design, AI Virtual Staging, AI Day-to-Dusk, AI Image Enhancement, and AI Item Removal (Decluttering). *** 2. **How secure is AI HomeDesign's API?** Our API is extremely secure. However, in the case of ANY issues, you can contact us at . We'll get back to you very soon as Enterprise users are our priority. *** 3. **How do I get more credits if I exceed my limit?** You have 3 options if you run out of credits before your subscription ends: a. You can re-purchase your current plan to get more credits. b. You can upgrade your plan and receive more credits. c. You can purchase credit packs on your current plan. *** 4. **How do I reset my API Key?** Simply open the API Access page on AI HomeDesign. Next, click on the *"Regenerate"* button to reset your key and get a new one.

Click on "Regenerate" button to access a new key

*** 5. **How do I report technical issues or errors?** In case of any technical issues, you can contact us at . \ We'll get back to you very soon as we understand these issues can disrupt your workflow.