> 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" ] } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://doc.aihomedesign.com/key-concepts/tools-and-widgets.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.