> 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/getting-started/quick-start-guide.md).

# 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: <your_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: <your_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: <your_api_key>' \
  --form 'project_id="<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: <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "order_id": "<order_id>",
    "tool": "tool-virtual-staging",
    "asset_map": {
      "tool-virtual-staging-input-image": "<asset_id>"
    },
    "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.md).
{% 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/<process_id>` 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 <your_webhook_url>               │
     │ ◄───────────────────────────────────── │  Result ready → final_assets[].src
     │                                        │
     │  GET result image URL                  │
     │ ─────────────────────────────────────► │  Download finished image
```