# Endpoints

## Test your setup

<mark style="color:blue;">`GET`</mark> `https://api.virtualstagingai.app/v1/ping`

Use this endpoint to test that your setup is working correctly. Returns some data about your account.

#### Headers

| Name          | Type   | Description                             |
| ------------- | ------ | --------------------------------------- |
| Authorization | String | Set to "Api-Key {your\_api\_key\_here}" |

{% tabs %}
{% tab title="200: OK Success" %}
Returns:

```
{
    userObj: {
        email: "...",
        uid: "..."
    },
    "photoLimit": 123,
    "photosUsedThisPeriod": 19
}
```

{% endtab %}
{% endtabs %}

## Create a new render

<mark style="color:green;">`POST`</mark> `https://api.virtualstagingai.app/v1/render/create`

This is the main endpoint of the API. It allows you to perform the following actions:

1. **Create a staging render**: Add virtual furniture to an image.
2. **Create a decluttered render**: Remove existing furniture from an image.
3. **Create a decluttered + staging render**: Remove existing furniture and add new virtual furniture to the same image.

#### How to Use:

1. **To create a staging render** (adding virtual furniture):
   * Set the required fields: `image_url`, `room_type`, `style`.
   * Set the `declutter_mode` parameter to `'off'` (default).
   * The image will be virtually staged with new furniture based on the provided style and room type.
2. **To create a decluttered render** (removing existing furniture without adding new furniture):
   * Set the required field: `image_url`.
   * Set the `declutter_mode` to `'on'`.
   * Set the `add_furniture` parameter to `false`.
   * This will only remove existing furniture, and the output will include the decluttered image.
3. **To create a decluttered + staging render** (removing existing furniture and adding new furniture):
   * Set the required fields: `image_url`, `room_type`, `style`.
   * Set the `declutter_mode` to `'on'` or `'auto'`.
   * Ensure the `add_furniture` parameter is `true` (default).
   * The output will include two images: one with the furniture removed and another with the new furniture added.

Maximum concurrency per API account: 50.

#### Headers

| Name                                            | Type   | Description                             |
| ----------------------------------------------- | ------ | --------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Set to "Api-Key {your\_api\_key\_here}" |

#### Request Body

| Name                                         | Type    | Description                                                                                                                                                                                                                                                                                                                                                           |
| -------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| image\_url<mark style="color:red;">\*</mark> | String  | URL of the image to add furniture to. If not provided, use the "file" parameter for form data uploads.                                                                                                                                                                                                                                                                |
| room\_type<mark style="color:red;">\*</mark> | String  | <p>The type of room in the uploaded photo. Must be one of: </p><p></p><p><code>\[ "living", "bed", "kitchen", "dining", "home\_office", "outdoor", "kids\_room" ]</code></p><p></p>                                                                                                                                                                                   |
| style<mark style="color:red;">\*</mark>      | String  | The desired style of furnishing. Must be one of the following: `["modern", "scandinavian", "industrial", "midcentury", "luxury", "farmhouse", "coastal", "standard"]`                                                                                                                                                                                                 |
| resolution                                   | String  | Resolution of the output image. Must be `4k` or `full-hd`                                                                                                                                                                                                                                                                                                             |
| file                                         | File    | Form data field to pass an image directly (if not using `image_url`). If you're using this, the other arguments have to be sent via URL query parameters.                                                                                                                                                                                                             |
| wait\_for\_completion                        | Boolean | If `false`, the response will include `{render_id}` instantly, and you can check render status via `GET /v1/render`. Default: `true`.                                                                                                                                                                                                                                 |
| add\_virtually\_staged\_watermark            | String  | Adds a small "Virtually Staged" disclaimer in the lower right corner of the rendered image                                                                                                                                                                                                                                                                            |
| declutter\_mode                              | String  | <p>Decluttering options:<br>- <code>'off'</code> (default): No decluttering.<br>- <code>'auto'</code>: Automatically declutter if furniture is detected.<br>- <code>'on'</code>: Always perform decluttering. If decluttering occurs, two outputs are created: a staged image and a decluttered image. Subsequent variations are staged on the decluttered image.</p> |
| declutter\_mask\_url                         | String  | URL of a black-and-white image to use as a mask for decluttering instead of automatically generating a mask. Use this if you want to allow your users to draw their own mask to decide which furniture gets removed and which doesn't.                                                                                                                                |
| add\_furniture                               | Boolean | <p>If <code>declutter\_mode</code> is <code>'on'</code>, this parameter controls whether to add new furniture:<br>- If <code>false</code>, only the decluttered image will be created without adding new furniture.<br>- Default: <code>true</code>.</p>                                                                                                              |

{% tabs %}
{% tab title="200: OK Success" %}
Returns:

```json5
{
    result_image_url: string, // only if "wait_for_completion" was set to true
    render_id: string,
    removal_output: string // only if "wait_for_completion" was set to true and decluttering was performed
}
```

Store the Render ID if you wish to create further variations for this photo, or look up the render state using `GET /v1/render`
{% endtab %}

{% tab title="405: Method Not Allowed When using an HTTP method different than POST" %}

{% endtab %}

{% tab title="401: Unauthorized Either your API key is invalid, or an error occurred during authentication" %}

{% endtab %}

{% tab title="403: Forbidden Authentication succeeded but you don't have a plan with API access, or have used up your renders." %}

{% endtab %}

{% tab title="400: Bad Request Invalid value for some parameter (body will contain an explanation)" %}

{% endtab %}
{% endtabs %}

## Get an existing render

<mark style="color:blue;">`GET`</mark> `https://api.virtualstagingai.app/v1/render`

Use this to retrieve information about an existing render (e.g. show your users progress after starting a render with `wait_for_completion=false`).&#x20;

This is available right after a render is created, even if the render status is `rendering`, so you can get the render info even if the render isn't done yet.

#### Query Parameters

| Name                                         | Type   | Description                                     |
| -------------------------------------------- | ------ | ----------------------------------------------- |
| render\_id<mark style="color:red;">\*</mark> | String | The render ID returned from `/v1/render/create` |

#### Headers

| Name                                            | Type   | Description                             |
| ----------------------------------------------- | ------ | --------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Set to "Api-Key {your\_api\_key\_here}" |

{% tabs %}
{% tab title="200: OK Success" %}
Returns:

```json5
{
    "render_id": "...",
    "status": "rendering" | "done" | "error",
    "created_at": 1685742540902, // epoch timestamp
    "outputs": string[], // will contain output image urls if status == "done". Will an entry for each new variation.
    "progress": 0.7432000000000001 // number 0-1
    "outputs_room_types": string[],
    "outputs_styles": string[]
}
```

{% endtab %}

{% tab title="405: Method Not Allowed Using different method than GET" %}

{% endtab %}

{% tab title="401: Unauthorized API key invalid or not provided" %}

{% endtab %}

{% tab title="403: Forbidden Authentication succeeded but your account doesn't have a plan with API access" %}

{% endtab %}

{% tab title="404: Not Found Render not found" %}

{% endtab %}

{% tab title="400: Bad Request No Render ID provided" %}

{% endtab %}
{% endtabs %}

## Create a variation for an existing render

<mark style="color:green;">`POST`</mark> `https://api.virtualstagingai.app/v1/render/create-variation`

Creates a variation for an existing render. The render has to have been created using `/v1/render/create` beforehand.&#x20;

All the same settings (`room_type`, etc.) from the first call will be used.

The render has to be in status `done` to start a new variation. The maximum amount of variations per render is 20.

#### Query Parameters

| Name       | Type   | Description                                     |
| ---------- | ------ | ----------------------------------------------- |
| render\_id | String | The render ID returned from `/v1/render/create` |

#### Headers

| Name                                            | Type   | Description                             |
| ----------------------------------------------- | ------ | --------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Set to "Api-Key {your\_api\_key\_here}" |

#### Request Body

| Name                              | Type    | Description                                                                                                                                                                                                                                                                                                                                                      |
| --------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| wait\_for\_completion             | Boolean | <p>If false, you'll get a response like <code>{render\_id}</code>  instantly and the result output will be added to the <code>outputs</code> array in the render object. </p><p></p><p>So when you retrieve the render object using <code>GET /v1/render</code>, the last element of <code>outputs</code> will contain the url to your new variation.</p><p></p> |
| roomType                          | String  | The type of room for the new variations. Must be one of: `living`, `bed`, `kitchen`, `dining`, `home_office`, `outdoor`, `kids_room`.                                                                                                                                                                                                                            |
| style                             | String  | The desired style of furnishing for the new variation. Must be in the following array: `["standard", "modern", "scandinavian", "industrial", "mid-century modern", "coastal", "american", "southwestern", "farmhouse", "luxury"]`                                                                                                                                |
| add\_virtually\_staged\_watermark | boolean |                                                                                                                                                                                                                                                                                                                                                                  |
| switch\_to\_queued\_immediately   | boolean | If true, will immediately switch render into "queued" status, then into "rendering" once the photo starts rendering.                                                                                                                                                                                                                                             |

{% tabs %}
{% tab title="200: OK " %}
Returns:

```json5
{
    result_image_url: string, // only if "wait_for_completion" was set to true
    render_id: string
}
```

Store the Render ID if you wish to create further variations for this photo, or look up the render state using `GET /v1/render`.&#x20;

If `wait_for_completion` was `false`, only the `render_id` will be returned and you'll have to look up the render state using `GET /v1/render`. Then, the output image of your variation will be appended to the `outputs` array and `status` will be `rendering` until the variation is done.
{% endtab %}

{% tab title="405: Method Not Allowed You're using a method other than POST" %}

{% endtab %}

{% tab title="401: Unauthorized API Key invalid or not provided" %}

{% endtab %}

{% tab title="403: Forbidden Authentication succeeded but your account doesn't have a plan with API access" %}

{% endtab %}

{% tab title="400: Bad Request render\_id not provided, or an invalid parameter provided in the request body" %}

{% endtab %}

{% tab title="404: Not Found Render with the passed ID not found " %}

{% endtab %}

{% tab title="500: Internal Server Error Unknown Error; reach out to support" %}

{% endtab %}
{% endtabs %}

## Get available room types & styles

<mark style="color:blue;">`GET`</mark> `https://api.virtualstagingai.app/v1/options`

Returns the available styles and room types. They need to be passed into other endpoints exactly as the same strings as returned here.

#### Headers

| Name                                            | Type   | Description                             |
| ----------------------------------------------- | ------ | --------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Set to "Api-Key {your\_api\_key\_here}" |

{% tabs %}
{% tab title="200: OK " %}
Returns:

```json5
{
    "styles": [
        "modern",
        "scandinavian",
        "industrial",
        "midcentury",
        "luxury",
        "farmhouse",
        "coastal",
        "standard"
    ],
    "roomTypes": [
        "living",
        "bed",
        "kitchen",
        "dining",
        "home_office",
        "outdoor",
        "kids_room"
    ]
}
```

{% endtab %}
{% endtabs %}


---

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