> For the complete documentation index, see [llms.txt](https://doc.aihomedesign.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.aihomedesign.com/key-concepts/tools-and-widgets.md). # 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" ] } ```