Home Staging AI v3

The Home Staging AI allows you to automatically create furnishings for residential interior spaces. Available as a service via API:

Home Staging AI

Test the API live in our interactive HomeStaging AI playground.

Furnish a Room

The example below lists all fields that could be included in the call request. To learn more about an individual field or its type scroll down to find it in the tables below. Dimensions and positions in the coordinate system are defined in meters, angles in arc degrees.

Note that a template describes a variable set of furniture, in a similar way as giving a list of furniture, using predefined furniture types and counts, and choosing from a default set of shapes. If both template and furniture are present in a request, they will be added together.

{
    "jsonrpc": "2.0",
    "method": "HomeStaging.furnish",
    "params": {
        // A Template is a predefined furniture list of furniture which will
        // be added in the furnishing result.
        "template":{
            "name": "living",
            // To exclude certain types of furniture from this template:
            "exclude": ["sideboard"]
        },
        // A flexible list of furniture items to be added to the furnishing
        // result. These furniture items will be added to the template.
        // Type, shape, count and placement can be specified.
        // To replace something from a template with fixed position: exclude
        // it in the template and add it here
        "furniture": [
            // Add one dinning table:
            { "type": "dining_table" },
            // And a desired amount of chairs:
            // (Resulting count might be less in favour of meaningful furnishings)
            { "type": "dining_chair", "targetCount": 4 },
            // Also add a table with a specific shape:
            {
                "type": "task_table",
                "shape": { "type": "cylinder", "r": 2.2, "h": 0.6 }
            },
            // … and a sideboard on a specific position [X,Y,Z], rotated by 90°
            {
                "type": "sideboard",
                "position": [ 2.2, 0.6, 0.4 ],
                "rotation": 90,
                "shape": { "type": "box", "a": 2.2, "b": 0.4, "h": 0.6 }
            }
        ],
        // Now let's describe the room to be furnished:
        "room": {
            "boundary": {
                "shape": {
                    "type": "polygon-extrusion",
                    // A closed 2D polygon on the XZ plane (floor)
                    "points": [[-2,2], [2,2], [2,-2], [-1.5,-2], [-2,-1]],
                    // Room height:
                    "h": 2.7
                },
                "openings": [
                    // Openings along the boundary polygon
                    { "type": "window", "pos": 1, "y": 0.6, "l": 1.6, "h": 1.6 },
                    { "type": "door", "pos": 4.2, "y": 0, "l": 0.8, "h": 2.1 }
                ]
            }
        },
        // You can tell the AI how many proposals it should try to generate:
        // (Fewer proposals might be little faster, but the calculation
        // time is not linearly proportional)
        "maxResults": 10
    },
    // UUID correlating to the one from the call request
    "id": "request-uuid-for-debugging"
}

Parameters

Validation

We provide JSON schema definitions for parameter validation.

Top Level

Conceptually there is two key pieces of information the AI needs to know:

  • The type and the amount of furniture you want to place in a room.
  • What the room does look like.

The furniture items can be specified as a list with the "furniture" parameter or by using a furniture "template". Templates are simply predefined lists of furniture items for your convenience. You can use either one of those parameters separately or both in combination.

Property Type Required Description
"room" object required A room description defining the geometry and semantics (i.e. windows, doors) of a room.
"template" object optional A furniture template object to be included in the furnishing result.
"furniture" array optional A list of furniture items to be included cumulatively in the furnishing result.
"maxResults" number optional Maximum number of results that shall be computed (1 - 20). Defaults to 10.

Furniture Template

A predefined list of furniture items. Can be specified in the "template" top level parameter.

Property Type Required Description
"name" string required The name of a furniture template. Available templates are listed bellow this table.
"exclude" array required A list of furniture types to be excluded from this template.

Example:

Let's say you want all the furniture items from the "living" template, except the sofa:

{
    "name": "living",
    "exclude": ["sofa"]
}
Available Templates:
  • bedroom
  • dining
  • dining_living
  • home_office
  • living

Furniture Item

Describes a single piece of furniture as an object in the "furniture" list top level parameter.

Property Type Required Description
"type" string required Furniture type name. There is a list of available furniture types below this table.
"targetCount" number optional The target amount of this furniture type to be included in a furnishing result. Must be a multiple of 1. Default value is 1. The item count in the result might be lower in favour of meaningful furnishings.
"position" array optional [X,Y,Z] Position of the shape origin point in meter units. Omit this value in order to receive a position proposal from the furnishing AI. This parameter is only available for furniture types: armchair, bed, dining_table, sofa, shelf, sideboard, task_table, wardrobe
"rotation" number optional Rotation in arc degree units. This value will be set by the furnishing AI if the position value is omitted.
"shape" object optional A shape describing the geometrical external boundary of a furniture item. Omit this value to receive a shape proposal from the furnishing AI. Allowed shape types for furniture items are: "box", "cylinder", "l-extrusion". Support for additional shapes like "polygons-extrusion" might be added in the future.
"customData" object optional A pass-through object which will be ignored by the AI and reappears in the result. You could for example store your own furniture ID here in order to correlate furniture items from your request to the ones in the result.

Example:

{
    "type": "sideboard",
    "position": [ 2.2, 0.6, 0.4 ],
    "rotation": 90,
    "shape": { "type": "box", "a": 2.2, "b": 0.4, "h": 0.6, "wallAlignment": "x-axis" },
    "customData": {
        "myFurnitureId": "to-find-this-item-in-the-result"
    }
}
Available Furniture Types:
  • armchair
  • bed
  • bed_lamp
  • coffee_table
  • dining_chair
  • dining_table
  • free_standing_lamp
  • nightstand
  • pendant_lamp
  • shelf
  • sideboard
  • sofa
  • task_chair
  • task_table
  • tv
  • wardrobe

Room

Property Type Required Description
"boundary" object required A room boundary object.

Room Boundary

Describes the outer boundary of a room. The boundary itself is considered to be a wall unless stated otherwise in the "openings" property.

Property Type Required Description
"shape" array required A polygon-extrusion shape describing the room boundary.
"openings" array optional Describes openings in the room polygon boundaries.

Room Boundary Openings

The AI takes room boundary openings into account to preserve circulation areas and to avoid placing furniture items in front of doors or windows. Dimensions are in meter units and relative to the room polygon boundary.

Property Type Required Description
"type" string required Can be one of "window", "door", "gap"
"pos" number required Position sliding along the room boundary polygon, starting at the first point.
"l" number required Length of the opening along the polygon boundary.
"y" number required Vertical position of the opening relative to the floor.
"h" number required Height of the opening.

Shape

A placeholder geometry describing the outer boundary of a furniture item or a room. All units are in meters and arc degrees.

Box Shape
Property Type Required Description
"type" string required = "box"
"a" number required Rectangle size along the X axis in meter units.
"b" number required Rectangle size along the Z axis in meter units.
"h" number required Extrusion height along the Y axis in meter units.
"wallAlignment" string optional Whether and how the shape should be aligned to a wall. Possible values: "none", "x-axis", "z-axis", "corner"
Cylinder Shape
Property Type Required Description
"type" string required = "cylinder"
"r" number required Radius in meter units.
"h" number required Extrusion height along the Y axis in meter units.
L-Extrusion Shape
Property Type Required Description
"type" string required = "l-extrusion"
"a" number required Bounding box size along the X axis in meter units.
"b" number required Bounding box size along the Z axis in meter units.
"c" number required Object depth along the X axis in meter units.
"d" number required Object depth along the Z axis in meter units.
"h" number required Extrusion height along the Y axis in meter units.
"wallAlignment" string optional Whether and how the shape should be aligned to a wall. Possible values: "none", "x-axis", "z-axis", "corner"
Polygon-Extrusion Shape
Property Type Required Description
"type" string required = "polygon-extrusion"
"points" array required A closed 2D polygon on the XZ plane (floor) describing. Format: [ [x1,z1], [x2,z2], [x3,z3], … ]
"h" number required Extrusion height along the Y axis in meter units.

Shape Axes in Relation to Furniture Types

Coordinate System

A three-dimensional, right-handed coordinate system with the Y axis pointing up. Positive rotations are in clockwise direction. Coordinate units are meters.

Result Response

Example:

{
    "jsonrpc": "2.0",
    "result": {
        "furnishings": [
            {
                // indicates how much in the room is occupied by furniture items
                // 0 = no area occupied (I.e. only pictures have been placed on walls)
                // 1 = area is occupied completely
                "density": 0.8,
                // A randomly assigned UUID for later feedback
                "id": "furnishing-uuid-for-feedback",
                // A list of placed furniture items
                "furniture": [
                    {
                        "type": "table",
                        "position": [ 0.3, 0, 2.2 ],
                        "rotation": 0,
                        "shape": { "type": "cylinder", "r": 0.75, "h": 0.72 },
                        "groupId": "a3628acb-ad8b-470f-a63c-60e08872b82e"
                    },
                    {
                        "type": "sideboard",
                        "position": [ 2, 0, 1.2 ],
                        "rotation": 90,
                        "shape": { "type": "box", "a": 2, "b": 0.6, "h": 0.4 },
                        "groupId": "0a25dcd2-0201-44b0-b184-ee94c859b166"
                    }
                ]
            }
        ],
        "warnings": [
            // suboptimal, non-breaking conditions
            {
                "code": "warning_5",
                "message": "Fixed furniture items overlap."
            }
        ]
    },
    // UUID correlating to the one from the call request
    "id": "request-uuid-for-debugging"
}

Result Warnings

Provides information on suboptimal, non-breaking conditions, not preventing the AI from generating furnishing results. Possible warnings are:

Code Message
warning_1 No furnishings found.
warning_2 Found only <n> furnishings.
warning_3 Not enough walls.
warning_4 Fixed furniture items are too close to each other.
warning_5 Fixed furniture items overlap.
warning_6 Some fixed furniture item is not fully inside the room.
warning_7 Position of an opening was larger than the circumference of the room.

Error Response

Indicates that the process could not finish. Please be aware that an error response always provides 2 error codes:

error.data[0].code = The HomeStaging API error code as described bellow.

error.code = Default JSON RPC 2 error code, not related to HomeStaging API.

Code Message
error_1 Code Error: <additional info>
error_2 Invalid request parameter: <additional info>
error_3 Room is too large. Please send a room no larger than <n> square meters.
error_4 The minimal area of the fixed furniture is too large. The maximum allowed is <n> square meters.
error_5 The minimal area of the fixed furniture is too large compared to the useful area of the room. The maximum allowed ratio is <n>.
error_6 Room is too small. Please send a room at least <n> square meters.

Example:

{
    "jsonrpc": "2.0",
    "error": {
        "data": [
            {
                // HomeStaging API error info
                "code": "error_6",
                "message": "Room is too small. Please send a room at least 2 square meters."
            }
        ],
        // Default JSON-RPC2 error info
        "code": -32602,
        "message": "Invalid params"
    },
    "id": "request-uuid-for-debugging"
}