Orders

What is an Order?

An Order bundles one or more input images together and makes them ready for AI processing. Think of it as the "job ticket" — you create it once per set of input photos, then fire as many processes against it as you want.

An order has:

• Entry assets — the original uploaded images

• Processes — all AI jobs run against this order

• Status — idle while waiting, active during processing

Asset roles

Role	Description
primary_angle	The main photo (required; only one allowed per order)
secondary_angle	An additional angle of the same space (only one allowed per order)
mask	A binary mask image used by mask-based tools

---

Create an Order (Upload Images)

POST https://api.aihomedesign.com/v3/order
x-api-key: <your_api_key>
Content-Type: multipart/form-data

Form field	Required	Description
project_id	Optional	ID of the project to attach this order to
asset_file	At least one	Image file(s) to upload — repeat for multiple files
asset_roles	Optional	Role for each file — positionally aligned with asset_files, defaults to primary_angle

Single image:

curl --location 'https://api.aihomedesign.com/v3/order' \
  --header 'x-api-key: <your_api_key>' \
  --form 'project_id="6984bd700fc3c3c614c2bea5"' \
  --form 'asset_file=@"/path/to/room.jpeg"'

Two images — primary + secondary angle:

curl --location 'https://api.aihomedesign.com/v3/order' \
  --header 'x-api-key: <your_api_key>' \
  --form 'project_id="6984bd700fc3c3c614c2bea5"' \
  --form 'asset_file=@"/path/to/house_front.jpeg"' \
  --form 'asset_file=@"/path/to/house_side.jpeg"' \
  --form 'asset_role="primary_angle"' \
  --form 'asset_role="secondary_angle"'

Upload Mask Image (Item Removal Mask tool)

curl --location 'https://api.aihomedesign.com/v3/order/:id/append' \
  --header 'x-api-key: <your_api_key>' \
  --form 'project_id="6984bd700fc3c3c614c2bea5"' \
  --form 'asset_file=@"/path/to/mask.png"' \
  --form 'asset_role="mask"' \
  --form 'asset_type="mask"' \

A binary mask image — blue (#7878CD) pixels = remove | black pixels = keep

Response (201 Created):

{
  "order_id": "69a6aa03a374700bff4a1328",
  "assets": [
    {
      "id": "69a6aa03a374700bff4a1327",
      "src": "https://cdn.aihomedesign.com/...",
      "asset_type": "image",
      "asset_role": "primary_angle"
    }
  ]
}

Save the order_id and each asset id — you need them when creating a process.

---

Fetch a Single Order

GET https://api.aihomedesign.com/v3/order/:id
x-api-key: <your_api_key>

Optional query params: width, height to resize image URLs.

Response:

{
  "id": "69a6aa03a374700bff4a1328",
  "project_id": "6984bd700fc3c3c614c2bea5",
  "entry_assets": [
    {
      "id": "69a6aa03a374700bff4a1327",
      "asset_type": "image",
      "asset_role": "primary_angle",
      "src": "https://cdn.aihomedesign.com/...",
      "thumbnail_src": "https://cdn.aihomedesign.com/.../thumb"
    }
  ],
  "status": "idle",
  "created_at": "2025-07-05T10:00:00Z",
  "updated_at": "2025-07-05T10:00:00Z",
  "processes": [
    {
      "id": "69a6bb11a374700bff4a1333",
      "tool": "tool-virtual-staging",
      "status": "done",
      "final_assets": [...]
    }
  ]
}