🛣️Endpoints

A directory of all Virtual Staging AI API endpoints.

Test your setup

GET https://api.virtualstagingai.app/v1/ping

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

Headers

NameTypeDescription

Authorization

String

Set to "Api-Key {your_api_key_here}"

Returns:

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

Create a new render

POST 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

NameTypeDescription

Authorization*

String

Set to "Api-Key {your_api_key_here}"

Request Body

NameTypeDescription

image_url*

String

URL of the image to add furniture to. If not provided, use the "file" parameter for form data uploads.

room_type*

String

The type of room in the uploaded photo. Must be one of:

[ "living", "bed", "kitchen", "dining", "bathroom", "home_office", "outdoor", "kids_room" ]

style*

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

Decluttering options: - 'off' (default): No decluttering. - 'auto': Automatically declutter if furniture is detected. - 'on': 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.

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

If declutter_mode is 'on', this parameter controls whether to add new furniture: - If false, only the decluttered image will be created without adding new furniture. - Default: true.

Returns:

{
    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

Get an existing render

GET 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).

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

NameTypeDescription

render_id*

String

The render ID returned from /v1/render/create

Headers

NameTypeDescription

Authorization*

String

Set to "Api-Key {your_api_key_here}"

Returns:

{
    "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[]
}

Create a variation for an existing render

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

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

NameTypeDescription

render_id

String

The render ID returned from /v1/render/create

Headers

NameTypeDescription

Authorization*

String

Set to "Api-Key {your_api_key_here}"

Request Body

NameTypeDescription

wait_for_completion

Boolean

If false, you'll get a response like {render_id} instantly and the result output will be added to the outputs array in the render object.

So when you retrieve the render object using GET /v1/render, the last element of outputs will contain the url to your new variation.

roomType

String

The type of room for the new variations. Must be one of: living, bed, kitchen, dining, bathroom, 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.

Returns:

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

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.

Get available room types & styles

GET 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

NameTypeDescription

Authorization*

String

Set to "Api-Key {your_api_key_here}"

Returns:

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

Last updated