Migrating from V1

V3 replaces the V1 API entirely. This page maps every V1 concept and endpoint to its V3 equivalent so you can migrate without guessing.

---

Concept Mapping

V1	V3	Notes
service_name (e.g. service-ai-virtual-staging)	tool slug (e.g. tool-virtual-staging)	Same idea, new naming scheme
space_name (e.g. space-bedroom)	Widget item slug (e.g. item-bedroom-widget-space-tool-virtual-staging)	Now part of the widgets array
Widget IDs (numeric)	Widget & item slugs (string)	Slugs are human-readable and self-describing
No project concept	POST /v3/project	Orders must now belong to a project

---

Endpoint Mapping

V1 endpoint	V3 equivalent	Key difference
POST /v1/order/image	POST /v3/order	Upload + order creation are now one call; returns order_id and assets[].id
POST /v1/order	POST /v3/process	The "submit order" step is now called "create process"
GET /v1/order/:id	GET /v3/order/:id	Response includes full processes array with results

---

Migration Steps

1. Create a project for each property you work with (POST /v3/project) — there is no V1 equivalent.

2. Replace your image upload call — instead of POST /v1/order/image, use POST /v3/order (multipart). It returns both order_id and asset IDs in one response.

3. Replace your order submission call — instead of POST /v1/order with service_name and space_name, use POST /v3/process with:

   • tool (slug)

   • asset_map (maps input slot slug → asset ID)

   • widgets (array of { slug, item_slugs })

4. Update your webhook handler — the V3 payload shape is richer; check Webhook Reference for the exact fields.

---

Example: V1 vs V3 Side by Side

V1 — upload image:

curl --location 'https://api.aihomedesign.com/v1/order/image' \
  --header 'x-api-key: <key>' \
  --form 'image=@"/path/to/room.jpg"' \
  --form 'service_name="service-ai-virtual-staging"'
# → returns { "order_id": "..." }

V3 — create order:

curl --location 'https://api.aihomedesign.com/v3/order' \
  --header 'x-api-key: <key>' \
  --form 'project_id="<project_id>"' \
  --form 'asset_file=@"/path/to/room.jpg"'
# → returns { "order_id": "...", "assets": [{ "id": "...", ... }] }

V1 — submit order:

curl --location 'https://api.aihomedesign.com/v1/order' \
  --header 'x-api-key: <key>' \
  --data '{
    "order_id": "...",
    "service_name": "service-ai-virtual-staging",
    "space_name": "space-bedroom",
    "widget_ids": [12, 34]
  }'

V3 — create process:

curl --location 'https://api.aihomedesign.com/v3/process' \
  --header 'x-api-key: <key>' \
  --data '{
    "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"]
      }
    ]
  }'