> 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
```


---

# 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/getting-started/quick-start-guide.md?ask=<question>
```

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.