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.

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.

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.

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:

{ "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.

Learn more about Tools and Widgets here.

---

Step 6 — Receive the Webhook Callback

Once the AI finishes, the platform POSTs the result to your registered webhook URL:

{
  "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:

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