# 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.

### 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

{% hint style="info" %}
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
{% endhint %}

## 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

{% hint style="info" %}
**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.
{% endhint %}

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 <mark style="color:blue;">`GET`</mark> request).

### Specifying a Base Variation ID

Base Variations can be specified when generating new Variations via <mark style="color:orange;">`POST`</mark>` `` ``/renders/{render_id}/variations.` For example:

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

{% hint style="info" %}
**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.
{% endhint %}

### 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 <mark style="color:orange;">`POST`</mark>`  ``/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).&#x20;

While the API supports synchronous processing via `wait_for_completion`, there's a current limitation with our hosting provider that causes requests to time out after 60 seconds. For operations that might take longer:

* Use webhooks (recommended for production use)
* Or use the direct v2 API endpoint if you must use synchronous processing:`https://us-central1-furniture-ai.cloudfunctions.net/apiV2`

#### 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.virtualstagingai.app/v2-api/core-concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.