> 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/processes.md).

# 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: <your_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": "<asset_id>"
}
```

Input slot names follow the pattern `<tool-slug>-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: <your_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                           |