📝Core Concepts

Renders & Variations

A Render represents a processing job for a single source image. When you create a Render, you specify:

• The source image URL(s)

• The type of processing you want (staging, day-to-dusk, or enhancement)

• How many Variations you want generated

A Variation is an individual result generated from that Render. For example, if you request 3 Variations of a virtual staging Render, you'll get 3 different furniture arrangements using the same style and room type.

Processing Types

Virtual Staging

Virtual staging allows you to add furniture and décor to empty rooms. When creating a staging Render, you specify:

• Room type (living room, bedroom, kitchen, etc.)

• Furniture style (modern, scandinavian, farmhouse, etc.)

• Whether to automatically remove existing furniture

The API will generate unique furniture arrangements based on your specifications. You can create multiple Variations to get different furniture layouts and arrangements.

Multi-View Staging (beta)

Multi-view staging allows you to consistently stage two images of the same room taken from different perspectives with the same furniture and layout.

As the feature is still in beta, there are a few limitations you should keep in mind when using it:

• We recommend checking the compatibility of images using the POST /multi-view-compatability endpoint before submitting them for render creation. For input images that are not compatible according to the result of said endpoint, a successful response from the POST /renders endpoint is not guaranteed.

• Our model currently works best with bed and living rooms, other room types are currently incompatible with multi-view staging but will follow in the future.

• Multi-view staging is not possible with furniture removal at this point in time. If you wish to use multi-view staging for images of a non-empty room, please create separate furniture removal renders first and then stage the outputs of those.

• The input images should have the same dimensions. Landscape images with a wide aspect ratio (e.g. 16:9 or 4:3) usually work best. Portrait images are not yet supported.

To achieve the best results, also consider the following advice:

• Large or complex rooms are more difficult to stage consistently, so for best results use it in on smaller, simpler spaces.

• Both input images should be taken from similar angles. For example, photos from opposite angles will not work well.

Day-to-Dusk

Day-to-dusk processing transforms daytime exterior photos into evening scenes. You can specify different sky styles:

• Dusk - Deep twilight tones

• Golden - Warm sunset lighting

• Blue - Early evening blue hour

Image Enhancement

Enhancement processing improves the overall quality of your photos by:

• Adjusting brightness and contrast

• Enhancing colors

• Improving sharpness

Creating Multiple Variations

There are two ways to create multiple Variations:

1. Initial Render: Specify variation_count when creating a new Render to generate multiple Variations immediately.

2. Add Later: Create additional Variations for an existing Render using the Variations endpoint. This is useful when you want to use the same source image but use a different configuration, such as creating another Staging Variation with a different furniture style, or creating a new Day to Dusk Variation with a different sky style

Variation limits: Up to 20 Variations can be generated for each Render. Attempting to generate Variations beyond this limit will result in an error response from the API

Furniture Analysis

Before creating a Staging Render, you can use the furniture analysis endpoint to:

1. Determine if furniture exists in the room

2. Generate a mask showing where existing furniture is located

3. Get a percentage of the image covered by furniture

This is useful for:

• Deciding whether to enable furniture removal

• Creating targeted removal masks for specific pieces

• Providing a base removal mask that can be edited by the user in your UI to show what furniture to remove

Base Variations in Virtual Staging

A Base Variation represents an intermediate state where furniture has been removed from an image, serving as the foundation for subsequent furniture staging operations. Base Variations are not a special type of Variation, they are simply Removal Variations that can be used as the underlying image when generating future Staging Variations. Specifying Base Variations as part of your workflow provides greater control over the end result, as it ensures that furniture is staged onto a specific underlying image.

How Base Variations are Generated

There are 2 cases in which Base Removal Variations will be automatically created:

• During initial Render creation when furniture Removal and Staging are both enabled

  • Note: If removal mode is "auto" and no furniture is detected, no removal variation will be created

• During additional Variation creation when furniture Removal and Staging are both enabled

  • Only occurs when no base_variation_id is specified

Example: If creating a new Render with 3 Variations and using both Removal and Staging options, 6 Variations will be created. 3 final results that are staged with furniture, and 3 intermediate Variations where only the furniture has been removed.

If a further 2 Variations are created on this Render and the base_variation_id is not specified then 4 more Variations will be created: 2 for Removal and 2 for Staging.

Each Removal Variation will have been created independently as this method is more efficient and results in faster image generation. Thus a Removal Variation will be created for each Staging Variation, which can be retrieved and stored like any other type of Variation. If a Base Variation has been generated, its ID will be available as base_variation_id on the related Staging Variation response (either via the Webhook payload or via a GET request).

Specifying a Base Variation ID

Base Variations can be specified when generating new Variations via POST /renders/{render_id}/variations. For example:

{
    "config": {
        "type": "staging",
        "add_furniture": {
            "style": "modern",
            "room_type": "living",
            "base_variation_id": "existing-variation-id"  // Reference to existing removal variation
        }
    },
    "variation_count": 1
}

In the example above, we are creating a new Staging Render using a specific Base Variation. It is important to note that this Base Variation could have either been created automatically by one of the methods discussed above, or manually - there is no distinction between the two.

Example: If creating a new Render with 2 Variations using only Removal options, 2 Removal Variations will be generated. Once these are complete, their IDs can be used as the base_variation_id for Staging Variations. If 2 new Staging Variations are created, each using the same Removal Variation as the base, then 4 Variations will have been generated in total: 2 Removal Variations, and 2 Staging Variations that have the same underlying image.

Important Notes

• Base Variations can only be referenced within the same render. You cannot specify an ID from another Render

• You cannot specify a base_variation_id during initial Render creation as no Variations will be available yet. They can only be specified when creating more Variation via POST /renders/{render_id}/variations

Best Practices with Base Variations

• If precise control of furniture removal is required, consider generating multiple Removal Variations with different masks and then creating Staging Variations using the best result

• If planning to create multiple Staging Variations after removing furniture from an image, store the Base Variation IDs to ensure that the underlying image will be consistent

Asynchronous Processing & Webhooks

The v2 API supports webhooks to deliver payloads to any defined URL upon completion of Variations (as well as any error states). While the API supports synchronous processing via wait_for_completion, we strongly recommend using webhooks for production applications for the following reasons:

Benefits of Webhooks

• Avoid timeout issues with longer renders

• Process multiple renders concurrently

• More resilient to network issues

• Better handling of retries and failures

• Reduced infrastructure cost by avoiding long running server requests