🛣️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

Name	Type	Description
Authorization	String	Set to "Api-Key {your_api_key_here}"

200: OK Success

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

Name	Type	Description
Authorization*	String	Set to "Api-Key {your_api_key_here}"

Request Body

Name	Type	Description
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.

200: OK Success

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

405: Method Not Allowed When using an HTTP method different than POST

401: Unauthorized Either your API key is invalid, or an error occurred during authentication

403: Forbidden Authentication succeeded but you don't have a plan with API access, or have used up your renders.

400: Bad Request Invalid value for some parameter (body will contain an explanation)

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

Name	Type	Description
render_id*	String	The render ID returned from /v1/render/create

Headers

Name	Type	Description
Authorization*	String	Set to "Api-Key {your_api_key_here}"

200: OK Success

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

405: Method Not Allowed Using different method than GET

401: Unauthorized API key invalid or not provided

403: Forbidden Authentication succeeded but your account doesn't have a plan with API access

404: Not Found Render not found

400: Bad Request No Render ID provided

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

Name	Type	Description
render_id	String	The render ID returned from /v1/render/create

Headers

Name	Type	Description
Authorization*	String	Set to "Api-Key {your_api_key_here}"

Request Body

Name	Type	Description
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.

200: OK

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.

405: Method Not Allowed You're using a method other than POST

401: Unauthorized API Key invalid or not provided

403: Forbidden Authentication succeeded but your account doesn't have a plan with API access

400: Bad Request render_id not provided, or an invalid parameter provided in the request body

404: Not Found Render with the passed ID not found

500: Internal Server Error Unknown Error; reach out to support

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

Name	Type	Description
Authorization*	String	Set to "Api-Key {your_api_key_here}"

200: OK

Returns:

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