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