# Endpoints The v2 API is available at the base URL `https://api.virtualstagingai.app/v2`. The same API key can be used for both the v1 and v2 API. You can find or generate your API key in the [Settings](https://www.virtualstagingai.app/settings) section of your Virtual Staging AI account. Authenticate all requests by including an Authorization Header with the value (case sensitive): `Authorization: Api-Key {your_api_key_here}` ## Check API status > Returns 200 OK if the API is running ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}}},"paths":{"/status":{"get":{"summary":"Check API status","description":"Returns 200 OK if the API is running","responses":{"200":{"description":"API is operational"}}}}}} ``` ## Get current user details > Returns information about the authenticated user including their usage limits ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"responses":{"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/user":{"get":{"summary":"Get current user details","description":"Returns information about the authenticated user including their usage limits","responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"email":{"type":"string"},"uid":{"type":"string"}}},"photoLimit":{"type":"object","properties":{"staging":{"oneOf":[{"type":"number"},{"type":"string","enum":["UNLIMITED"]}],"description":"The virtual staging photo limit. Can be a number or \"UNLIMITED\"."},"imageEditing":{"oneOf":[{"type":"number"},{"type":"string","enum":["UNLIMITED"]}],"description":"The image editing photo limit. Can be a number or \"UNLIMITED\"."}},"description":"The user's photo limit. Can be a number or the string \"UNLIMITED\" for unlimited plans."},"photosUsedThisPeriod":{"type":"object","properties":{"staging":{"type":"number","description":"Number of virtual staging photos used in the current period."},"imageEditing":{"type":"number","description":"Number of image editing photos used in the current period."}},"description":"Count of photos used in the current billing period by type."}}}}}},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ## Get all renders > Returns all renders for the authenticated user ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"schemas":{"Render":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this render."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"queued_at":{"type":["number","null"],"description":"Timestamp when the render was queued for processing (epoch milliseconds)."},"variations":{"type":"object","properties":{"total_count":{"type":"number","description":"Total number of completed variations for this render."},"next_cursor":{"type":["string","null"],"description":"Cursor to use to get the next page of variations."},"items":{"type":"array","description":"List of variations for this render.","items":{"$ref":"#/components/schemas/Variation"}}},"required":["total_count"]},"eta":{"type":["number","null"],"description":"Estimated time remaining for the first variation to complete (epoch milliseconds timestamp)."}},"required":["id","created_at","variations","eta"]},"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]}},"responses":{"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/renders":{"get":{"summary":"Get all renders","description":"Returns all renders for the authenticated user","parameters":[{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"in":"query","name":"cursor","schema":{"type":"string"},"description":"Render ID to start after"},{"in":"query","name":"order","description":"The order in which to display renders. Based on their creation date.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"total_count":{"type":"number","description":"The total number of completed variations for this render."},"next_cursor":{"type":["string","null"],"description":"The cursor to use to get the next page of renders."},"items":{"type":"array","items":{"$ref":"#/components/schemas/Render","description":"A list of renders."}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` {% hint style="warning" %} **Deprecated styles:** Please note that the `hamptons`, `american`, and `southwestern` styles have been deprecated, and now are mapped to other existing styles. The API will continue to support their use, but they may be removed in future versions {% endhint %} ## Create a new render > Create a new render with either a single configuration or multiple configurations.\ > \ > \*\*Single Config Format\*\*: Use this for creating a single render with one configuration.\ > \*\*Multi Config Format\*\*: Use this for creating a single render with multiple configurations. This can be used to generate variations with different room styles, furniture etc. without having to make a new request.\ > \ > \## Examples\ > \ > \### Single Config (Staging)\ > \`\`\`json\ > {\ > "config": {\ > "type": "staging",\ > "add\_furniture": {\ > "room\_type": "living",\ > "style": "modern"\ > }\ > },\ > "image\_url": " > "variation\_count": 3,\ > "wait\_for\_completion": false\ > }\ > \`\`\`\ > \ > \### Multi Config (Multiple Staging Variations)\ > \`\`\`json\ > {\ > "configs": \[\ > {\ > "type": "staging",\ > "add\_furniture": {\ > "room\_type": "living",\ > "style": "modern"\ > },\ > "variation\_count": 2\ > },\ > {\ > "type": "staging",\ > "add\_furniture": {\ > "room\_type": "living",\ > "style": "scandinavian"\ > },\ > "variation\_count": 1\ > }\ > ],\ > "image\_url": " > "wait\_for\_completion": true\ > }\ > \`\`\`\ > \ > \### Single Config (Day to Dusk)\ > \`\`\`json\ > {\ > "config": {\ > "type": "daytodusk",\ > "sky\_style": "golden"\ > },\ > "image\_url": " > "variation\_count": 1\ > }\ > \`\`\`
````json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"schemas":{"RenderStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/RoomType"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]},"VariationStagingConfigWithVariationCount":{"allOf":[{"$ref":"#/components/schemas/VariationStagingConfig"},{"type":"object","properties":{"variation_count":{"type":"integer","minimum":1,"description":"Number of variations to create with this configuration."}},"required":["variation_count"]}]},"VariationStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/RoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"DayToDuskConfigWithVariationCount":{"allOf":[{"$ref":"#/components/schemas/DayToDuskConfig"},{"type":"object","properties":{"variation_count":{"type":"integer","minimum":1,"description":"Number of variations to create with this configuration."}},"required":["variation_count"]}]},"EnhancementConfigWithVariationCount":{"allOf":[{"$ref":"#/components/schemas/EnhancementConfig"},{"type":"object","properties":{"variation_count":{"type":"integer","minimum":1,"description":"Number of variations to create with this configuration."}},"required":["variation_count"]}]},"DoneWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that completed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that completed."},"base_variation_id":{"type":["string","null"],"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["done"],"description":"Event type indicating successful completion."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Generated result images."}},"required":["event_type","result","render_id","variation_id","variation_type","timestamp","base_variation_id"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"ErrorWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that failed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that failed."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["error"],"description":"Event type indicating an error occurred."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["event_type","error_message","render_id","variation_id","variation_type","timestamp"]},"UpdateWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that was updated."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that was updated."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["update"],"description":"Event type indicating a status update."},"variation_status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"eta":{"type":"number","description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."}},"required":["event_type","variation_status","eta","render_id","variation_id","variation_type","timestamp"]},"Render":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this render."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"queued_at":{"type":["number","null"],"description":"Timestamp when the render was queued for processing (epoch milliseconds)."},"variations":{"type":"object","properties":{"total_count":{"type":"number","description":"Total number of completed variations for this render."},"next_cursor":{"type":["string","null"],"description":"Cursor to use to get the next page of variations."},"items":{"type":"array","description":"List of variations for this render.","items":{"$ref":"#/components/schemas/Variation"}}},"required":["total_count"]},"eta":{"type":["number","null"],"description":"Estimated time remaining for the first variation to complete (epoch milliseconds timestamp)."}},"required":["id","created_at","variations","eta"]},"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]}},"responses":{"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"ForbiddenError":{"description":"Forbidden error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/renders":{"post":{"summary":"Create a new render","description":"Create a new render with either a single configuration or multiple configurations.\n\n**Single Config Format**: Use this for creating a single render with one configuration.\n**Multi Config Format**: Use this for creating a single render with multiple configurations. This can be used to generate variations with different room styles, furniture etc. without having to make a new request.\n\n## Examples\n\n### Single Config (Staging)\n```json\n{\n \"config\": {\n \"type\": \"staging\",\n \"add_furniture\": {\n \"room_type\": \"living\",\n \"style\": \"modern\"\n }\n },\n \"image_url\": \"https://example.com/image.jpg\",\n \"variation_count\": 3,\n \"wait_for_completion\": false\n}\n```\n\n### Multi Config (Multiple Staging Variations)\n```json\n{\n \"configs\": [\n {\n \"type\": \"staging\",\n \"add_furniture\": {\n \"room_type\": \"living\",\n \"style\": \"modern\"\n },\n \"variation_count\": 2\n },\n {\n \"type\": \"staging\",\n \"add_furniture\": {\n \"room_type\": \"living\",\n \"style\": \"scandinavian\"\n },\n \"variation_count\": 1\n }\n ],\n \"image_url\": \"https://example.com/image.jpg\",\n \"wait_for_completion\": true\n}\n```\n\n### Single Config (Day to Dusk)\n```json\n{\n \"config\": {\n \"type\": \"daytodusk\",\n \"sky_style\": \"golden\"\n },\n \"image_url\": \"https://example.com/image.jpg\",\n \"variation_count\": 1\n}\n```\n","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["config","image_url","variation_count"],"additionalProperties":false,"properties":{"config":{"oneOf":[{"$ref":"#/components/schemas/RenderStagingConfig"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}]},"image_url":{"$ref":"#/components/schemas/ImageUrl"},"variation_count":{"type":"integer","minimum":1,"description":"Number of variations to create with this configuration"},"webhook_url":{"type":["string","null"],"format":"uri"},"wait_for_completion":{"type":["boolean","null"],"default":false}}},{"type":"object","required":["configs","image_url"],"additionalProperties":false,"properties":{"configs":{"oneOf":[{"type":"array","items":{"$ref":"#/components/schemas/VariationStagingConfigWithVariationCount"},"minItems":1,"description":"Array of staging configurations, each with its own variation count"},{"type":"array","items":{"$ref":"#/components/schemas/DayToDuskConfigWithVariationCount"},"minItems":1,"description":"Array of day-to-dusk configurations, each with its own variation count"},{"type":"array","items":{"$ref":"#/components/schemas/EnhancementConfigWithVariationCount"},"minItems":1,"description":"Array of enhancement configurations, each with its own variation count"}]},"image_url":{"$ref":"#/components/schemas/ImageUrl"},"webhook_url":{"type":["string","null"],"format":"uri"},"wait_for_completion":{"type":["boolean","null"],"default":false}}}]}}}},"callbacks":{"renderWebhook":{"{$request.body.webhook_url}":{"post":{"description":"Webhook response sent upon the completion of each variation that is part of the render","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DoneWebhookResponse"},{"$ref":"#/components/schemas/ErrorWebhookResponse"},{"$ref":"#/components/schemas/UpdateWebhookResponse"}]}}}},"responses":{"200":{"description":"Webhook received successfully"}}}}}},"responses":{"200":{"description":"Render created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"201":{"description":"Render created and queued for processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ```` ## Get render details > Returns details about a render including the status, variations, and result URL ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"schemas":{"Render":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this render."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"queued_at":{"type":["number","null"],"description":"Timestamp when the render was queued for processing (epoch milliseconds)."},"variations":{"type":"object","properties":{"total_count":{"type":"number","description":"Total number of completed variations for this render."},"next_cursor":{"type":["string","null"],"description":"Cursor to use to get the next page of variations."},"items":{"type":"array","description":"List of variations for this render.","items":{"$ref":"#/components/schemas/Variation"}}},"required":["total_count"]},"eta":{"type":["number","null"],"description":"Estimated time remaining for the first variation to complete (epoch milliseconds timestamp)."}},"required":["id","created_at","variations","eta"]},"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]}},"responses":{"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/renders/{render_id}":{"get":{"summary":"Get render details","description":"Returns details about a render including the status, variations, and result URL","parameters":[{"in":"path","name":"render_id","required":true,"schema":{"type":"string"},"description":"The ID of the render to get details for"},{"in":"query","name":"include_variations","schema":{"type":"boolean","default":false}},{"in":"query","name":"variations_limit","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"in":"query","name":"variations_cursor","schema":{"type":"string"},"description":"Variation ID to start after"},{"in":"query","name":"variations_order","description":"The order in which to display variations. Based on their creation date.","schema":{"type":"string","enum":["asc","desc"],"default":"asc"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"401":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ## Get variation details > Returns details about a variation including the status and result URL ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"schemas":{"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]}},"responses":{"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/renders/{render_id}/variations/{variation_id}":{"get":{"summary":"Get variation details","description":"Returns details about a variation including the status and result URL","parameters":[{"in":"path","name":"render_id","required":true,"schema":{"type":"string"},"description":"The ID of the base render"},{"in":"path","name":"variation_id","required":true,"schema":{"type":"string"},"description":"The ID of the variation to get details for"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Variation"}}}},"401":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ## Create new variations > Create one or more variations for an existing render. Status updates will be sent to the webhook\_url specified in the render if one was provided. ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"schemas":{"VariationStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/RoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]},"DoneWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that completed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that completed."},"base_variation_id":{"type":["string","null"],"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["done"],"description":"Event type indicating successful completion."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Generated result images."}},"required":["event_type","result","render_id","variation_id","variation_type","timestamp","base_variation_id"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"ErrorWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that failed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that failed."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["error"],"description":"Event type indicating an error occurred."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["event_type","error_message","render_id","variation_id","variation_type","timestamp"]},"UpdateWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that was updated."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that was updated."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["update"],"description":"Event type indicating a status update."},"variation_status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"eta":{"type":"number","description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."}},"required":["event_type","variation_status","eta","render_id","variation_id","variation_type","timestamp"]},"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]}},"responses":{"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"ForbiddenError":{"description":"Forbidden error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/renders/{render_id}/variations":{"post":{"summary":"Create new variations","description":"Create one or more variations for an existing render. Status updates will be sent to the webhook_url specified in the render if one was provided.","parameters":[{"in":"path","name":"render_id","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["config","variation_count"],"additionalProperties":false,"properties":{"config":{"oneOf":[{"$ref":"#/components/schemas/VariationStagingConfig"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}]},"variation_count":{"type":"integer","minimum":1},"wait_for_completion":{"type":["boolean","null"],"default":false}}}}}},"callbacks":{"variationWebhook":{"{$parent_render.webhook_url}":{"post":{"requestBody":{"description":"Webhook response sent upon the completion of each variation. The response is sent to the webhook_url specified in the parent render.","required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DoneWebhookResponse"},{"$ref":"#/components/schemas/ErrorWebhookResponse"},{"$ref":"#/components/schemas/UpdateWebhookResponse"}]}}}},"responses":{"200":{"description":"Webhook received successfully"}}}}}},"responses":{"200":{"description":"Variations created and completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"variations":{"type":"array","items":{"$ref":"#/components/schemas/Variation"}}}}}}},"201":{"description":"Variations created and processing started","content":{"application/json":{"schema":{"type":"object","properties":{"variations":{"type":"array","items":{"$ref":"#/components/schemas/Variation"}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ## Create multiple renders in bulk > Creates multiple renders with the specified parameters. ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"schemas":{"RenderStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/RoomType"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]},"DoneWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that completed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that completed."},"base_variation_id":{"type":["string","null"],"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["done"],"description":"Event type indicating successful completion."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Generated result images."}},"required":["event_type","result","render_id","variation_id","variation_type","timestamp","base_variation_id"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"ErrorWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that failed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that failed."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["error"],"description":"Event type indicating an error occurred."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["event_type","error_message","render_id","variation_id","variation_type","timestamp"]},"UpdateWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that was updated."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that was updated."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["update"],"description":"Event type indicating a status update."},"variation_status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"eta":{"type":"number","description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."}},"required":["event_type","variation_status","eta","render_id","variation_id","variation_type","timestamp"]},"Render":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this render."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"queued_at":{"type":["number","null"],"description":"Timestamp when the render was queued for processing (epoch milliseconds)."},"variations":{"type":"object","properties":{"total_count":{"type":"number","description":"Total number of completed variations for this render."},"next_cursor":{"type":["string","null"],"description":"Cursor to use to get the next page of variations."},"items":{"type":"array","description":"List of variations for this render.","items":{"$ref":"#/components/schemas/Variation"}}},"required":["total_count"]},"eta":{"type":["number","null"],"description":"Estimated time remaining for the first variation to complete (epoch milliseconds timestamp)."}},"required":["id","created_at","variations","eta"]},"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]}},"responses":{"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"ForbiddenError":{"description":"Forbidden error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/renders/bulk":{"post":{"summary":"Create multiple renders in bulk","description":"Creates multiple renders with the specified parameters.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["renders"],"additionalProperties":false,"properties":{"webhook_url":{"type":["string","null"],"format":"uri"},"wait_for_completion":{"type":["boolean","null"],"default":false},"renders":{"type":"array","minItems":1,"items":{"type":"object","required":["config","image_url","variation_count"],"additionalProperties":false,"properties":{"config":{"oneOf":[{"$ref":"#/components/schemas/RenderStagingConfig"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}]},"image_url":{"$ref":"#/components/schemas/ImageUrl"},"variation_count":{"type":"integer","minimum":1}}}}}}}}},"callbacks":{"renderWebhook":{"{$request.body.webhook_url}":{"post":{"description":"Webhook response sent upon the completion of each variation that is part of any render in the bulk request","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DoneWebhookResponse"},{"$ref":"#/components/schemas/ErrorWebhookResponse"},{"$ref":"#/components/schemas/UpdateWebhookResponse"}]}}}},"responses":{"200":{"description":"Webhook received successfully"}}}}}},"responses":{"200":{"description":"Renders created and completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"renders":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/Render"},{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"Error message describing what went wrong"},"original_image_url":{"type":"string","description":"URL of the image that failed processing"}}}]}}}}}}},"201":{"description":"Renders created and queued for processing","content":{"application/json":{"schema":{"type":"object","properties":{"renders":{"type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/Render"},{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"Error message describing what went wrong"},"original_image_url":{"type":"string","description":"URL of the image that failed processing"}}}]}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ## Create multiple variations in bulk > Creates multiple variations for an existing render with different configurations. ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"schemas":{"VariationStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/RoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]},"DoneWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that completed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that completed."},"base_variation_id":{"type":["string","null"],"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["done"],"description":"Event type indicating successful completion."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Generated result images."}},"required":["event_type","result","render_id","variation_id","variation_type","timestamp","base_variation_id"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"ErrorWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that failed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that failed."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["error"],"description":"Event type indicating an error occurred."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["event_type","error_message","render_id","variation_id","variation_type","timestamp"]},"UpdateWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that was updated."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that was updated."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["update"],"description":"Event type indicating a status update."},"variation_status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"eta":{"type":"number","description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."}},"required":["event_type","variation_status","eta","render_id","variation_id","variation_type","timestamp"]},"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]}},"responses":{"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"ForbiddenError":{"description":"Forbidden error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/renders/variations/bulk":{"post":{"summary":"Create multiple variations in bulk","description":"Creates multiple variations for an existing render with different configurations.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["renders"],"additionalProperties":false,"properties":{"wait_for_completion":{"type":["boolean","null"],"default":false},"renders":{"type":"array","minItems":1,"items":{"type":"object","required":["render_id","variation_count","config"],"additionalProperties":false,"properties":{"render_id":{"type":"string"},"variation_count":{"type":"integer","minimum":1},"config":{"oneOf":[{"$ref":"#/components/schemas/VariationStagingConfig"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}]}}}}}}}}},"callbacks":{"variationWebhook":{"{$parent_render.webhook_url}":{"post":{"description":"Webhook response sent upon the completion of each variation. The response is sent to the webhook_url specified in each parent render.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/DoneWebhookResponse"},{"$ref":"#/components/schemas/ErrorWebhookResponse"},{"$ref":"#/components/schemas/UpdateWebhookResponse"}]}}}},"responses":{"200":{"description":"Webhook received successfully"}}}}}},"responses":{"200":{"description":"Variations for renders created and completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Variation"},{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"Error message describing what went wrong"},"render_id":{"type":"string","description":"ID of the render that failed processing"}}}]}}}}}}},"201":{"description":"Variations for renders created and processing started","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Variation"},{"type":"object","properties":{"status":{"type":"string","enum":["error"]},"message":{"type":"string","description":"Error message describing what went wrong"},"render_id":{"type":"string","description":"ID of the render that failed processing"}}}]}}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ## Submit an image for a furniture mask generation > Submits an image for analysis to generate a furniture mask. If a webhook\_url is provided, completion status will be sent to that URL. ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"schemas":{"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"AnalysisDoneWebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"Analysis ID."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["analysis_completion"],"description":"Event type indicating successful analysis completion."},"percentage_masked":{"type":"number","description":"Percentage of the image that was identified as furniture."},"result_url":{"type":"string","description":"URL of the analysis result image."}},"required":["event_type","result_url","id","percentage_masked","timestamp"]},"AnalysisErrorWebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"Analysis ID."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["analysis_error"],"description":"Event type indicating analysis failure."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["id","timestamp","event_type","error_message"]},"Analysis":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this analysis."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"result_url":{"type":"string","description":"URL of the analysis result image."},"percentage_masked":{"type":"number","description":"Percentage of the image that was identified as furniture."},"status":{"type":"string","enum":["done","error"],"description":"Status of the analysis."}},"required":["id","created_at","result_url","status"]}},"responses":{"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/analyze":{"post":{"summary":"Submit an image for a furniture mask generation","description":"Submits an image for analysis to generate a furniture mask. If a webhook_url is provided, completion status will be sent to that URL.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["image_url"],"additionalProperties":false,"properties":{"image_url":{"$ref":"#/components/schemas/ImageUrl"},"webhook_url":{"type":["string","null"],"format":"uri","description":"URL for completion payload"}}}}}},"callbacks":{"analysisWebhook":{"{$request.body.webhook_url}":{"post":{"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AnalysisDoneWebhookResponse"},{"$ref":"#/components/schemas/AnalysisErrorWebhookResponse"}]}}}},"responses":{"200":{"description":"Webhook received successfully"}}}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Analysis"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthError"},"404":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ## Create or update webhook secret > Sets or updates the webhook secret used for HMAC signature verification ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"responses":{"ValidationError":{"description":"Validation error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"errors":{"type":"array","items":{"type":"string"}}},"required":["message"]}}}},"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/user/webhook-secret":{"post":{"summary":"Create or update webhook secret","description":"Sets or updates the webhook secret used for HMAC signature verification","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["webhook_secret"],"additionalProperties":false,"properties":{"webhook_secret":{"type":"string","minLength":1,"pattern":"^[a-zA-Z0-9_-]+$","description":"The webhook secret to use for HMAC signature verification"}}}}}},"responses":{"200":{"description":"Webhook secret updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ## Remove webhook secret > Removes the webhook secret used for HMAC signature verification ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"servers":[{"url":"https://api.virtualstagingai.app/v2","description":"Production base URL."},{"url":"https://us-central1-furniture-ai.cloudfunctions.net/apiV2","description":"Long-running operations endpoint."}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"API key authentication. Use the format: Api-Key ${key}."}},"responses":{"AuthError":{"description":"Authentication error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}},"UnexpectedError":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}}}}}},"paths":{"/user/webhook-secret":{"delete":{"summary":"Remove webhook secret","description":"Removes the webhook secret used for HMAC signature verification","responses":{"200":{"description":"Webhook secret removed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/AuthError"},"500":{"$ref":"#/components/responses/UnexpectedError"}}}}}} ``` ### Schemas ## The ImageUrl object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."}}}} ``` ## The FurnitureStyles object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]}}}} ``` ## The RoomType object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."}}}} ``` ## The SkyStyle object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."}}}} ``` ## The DayToDuskConfig object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."}}}} ``` ## The EnhancementConfig object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."}}}} ``` ## The LegacyStagingConfig object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]}}}} ``` ## The ImageResult object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]}}}} ``` ## The Variation object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]}}}} ``` ## The Render object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"Render":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this render."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"queued_at":{"type":["number","null"],"description":"Timestamp when the render was queued for processing (epoch milliseconds)."},"variations":{"type":"object","properties":{"total_count":{"type":"number","description":"Total number of completed variations for this render."},"next_cursor":{"type":["string","null"],"description":"Cursor to use to get the next page of variations."},"items":{"type":"array","description":"List of variations for this render.","items":{"$ref":"#/components/schemas/Variation"}}},"required":["total_count"]},"eta":{"type":["number","null"],"description":"Estimated time remaining for the first variation to complete (epoch milliseconds timestamp)."}},"required":["id","created_at","variations","eta"]},"Variation":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this variation."},"type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation (staging, removal, etc.)."},"render_id":{"type":"string","description":"ID of the parent render this variation belongs to."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Result images (only present when status is 'done')."},"base_variation_id":{"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base.","type":"string"},"eta":{"type":["number","null"],"description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."},"config":{"oneOf":[{"$ref":"#/components/schemas/LegacyStagingConfig"},{"$ref":"#/components/schemas/VariationStagingConfigRead"},{"$ref":"#/components/schemas/DayToDuskConfig"},{"$ref":"#/components/schemas/EnhancementConfig"}],"description":"Configuration used to generate this variation."}},"required":["id","render_id","created_at","status","eta"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"LegacyStagingConfig":{"type":"object","properties":{"type":{"type":"string","enum":["legacy_staging"]},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"style":{"$ref":"#/components/schemas/FurnitureStyles"}},"required":["room_type","style","type"]},"AnyRoomType":{"oneOf":[{"$ref":"#/components/schemas/RoomType"},{"type":"string","enum":["bathroom"],"deprecated":true,"description":"Deprecated. Not accepted for new staging requests; may appear in historical variation data."}],"description":"Room type (active or deprecated). Use for reading variation/config output only."},"RoomType":{"type":"string","enum":["living","bed","kitchen","dining","home_office","outdoor","kids_room"],"description":"Room types accepted for new staging requests (bathroom excluded)."},"FurnitureStyles":{"oneOf":[{"type":"string","enum":["standard","modern","scandinavian","industrial","midcentury","luxury","farmhouse","coastal"],"description":"Available furniture styles for staging."},{"type":"string","enum":["american","southwestern","hamptons"],"deprecated":true,"description":"Deprecated styles. These will be mapped to the closest existing style and are available only for backwards compatibility."}]},"VariationStagingConfigRead":{"type":"object","properties":{"type":{"type":"string","enum":["staging"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"add_virtually_staged_watermark":{"type":["boolean","null"],"description":"Whether to add a 'virtually staged' watermark to the output image."},"add_furniture":{"type":"object","properties":{"style":{"$ref":"#/components/schemas/FurnitureStyles"},"room_type":{"$ref":"#/components/schemas/AnyRoomType"},"base_variation_id":{"description":"ID of an existing removal variation that is being used as the base for this staging variation. This should be used to create multiple staging variations from a single removal variation.","type":"string"}},"required":["style","room_type"],"description":"Configuration for adding furniture to the image."},"remove_furniture":{"type":"object","properties":{"mode":{"type":"string","enum":["on","off","auto"],"description":"Furniture removal mode to use."},"mask_url":{"$ref":"#/components/schemas/ImageUrl","description":"URL of the mask image indicating areas to remove furniture from."}},"required":["mode"],"description":"Configuration for removing furniture from the image."}},"required":["type"]},"OutputResolution":{"oneOf":[{"type":"integer","enum":[1536],"description":"Force output to 1536px resolution regardless of input size"},{"type":"string","enum":["default"],"description":"Smart resolution: For Staging renders, upscale to 1536px minimum, or 3072px if input is larger than 1536px. For Enhancements and Day to Dusk renders, return size as-is to a maximum of 3072px."}],"default":"default","description":"Output image resolution. Use 'default' for smart resolution handling or 1536 to force 1536px output. Defaults to 'default' when omitted."},"ImageUrl":{"type":"string","pattern":"^(https?:\\/\\/[^\\s]+|data:image\\/[a-zA-Z+]+;base64,[A-Za-z0-9+/=]+)$","description":"URL for an image, either HTTP/HTTPS URL or base64 encoded data URL."},"DayToDuskConfig":{"type":"object","properties":{"type":{"type":"string","enum":["daytodusk"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"},"sky_style":{"$ref":"#/components/schemas/SkyStyle"}},"required":["sky_style","type"]},"SkyStyle":{"type":"string","enum":["dusk","golden","blue"],"description":"Available sky styles for day-to-dusk transformations."},"EnhancementConfig":{"type":"object","properties":{"type":{"type":"string","enum":["enhancement"]},"output_resolution":{"$ref":"#/components/schemas/OutputResolution"}},"required":["type"]}}}} ``` ## The Analysis object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"Analysis":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for this analysis."},"created_at":{"type":"number","description":"Creation timestamp (epoch milliseconds)."},"result_url":{"type":"string","description":"URL of the analysis result image."},"percentage_masked":{"type":"number","description":"Percentage of the image that was identified as furniture."},"status":{"type":"string","enum":["done","error"],"description":"Status of the analysis."}},"required":["id","created_at","result_url","status"]}}}} ``` ## The AnalysisDoneWebhookResponse object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"AnalysisDoneWebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"Analysis ID."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["analysis_completion"],"description":"Event type indicating successful analysis completion."},"percentage_masked":{"type":"number","description":"Percentage of the image that was identified as furniture."},"result_url":{"type":"string","description":"URL of the analysis result image."}},"required":["event_type","result_url","id","percentage_masked","timestamp"]}}}} ``` ## The AnalysisErrorWebhookResponse object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"AnalysisErrorWebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"Analysis ID."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["analysis_error"],"description":"Event type indicating analysis failure."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["id","timestamp","event_type","error_message"]}}}} ``` ## The DoneWebhookResponse object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"DoneWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that completed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that completed."},"base_variation_id":{"type":["string","null"],"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["done"],"description":"Event type indicating successful completion."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Generated result images."}},"required":["event_type","result","render_id","variation_id","variation_type","timestamp","base_variation_id"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]}}}} ``` ## The ErrorWebhookResponse object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"ErrorWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that failed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that failed."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["error"],"description":"Event type indicating an error occurred."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["event_type","error_message","render_id","variation_id","variation_type","timestamp"]}}}} ``` ## The UpdateWebhookResponse object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"UpdateWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that was updated."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that was updated."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["update"],"description":"Event type indicating a status update."},"variation_status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"eta":{"type":"number","description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."}},"required":["event_type","variation_status","eta","render_id","variation_id","variation_type","timestamp"]}}}} ``` ## The WebhookResponse object ```json {"openapi":"3.1.0","info":{"title":"Virtual Staging AI API","version":"2.0.0"},"components":{"schemas":{"WebhookResponse":{"oneOf":[{"$ref":"#/components/schemas/DoneWebhookResponse"},{"$ref":"#/components/schemas/ErrorWebhookResponse"},{"$ref":"#/components/schemas/UpdateWebhookResponse"},{"$ref":"#/components/schemas/AnalysisDoneWebhookResponse"},{"$ref":"#/components/schemas/AnalysisErrorWebhookResponse"}],"description":"Webhook response payload for various events."},"DoneWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that completed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that completed."},"base_variation_id":{"type":["string","null"],"description":"ID of the removal variation used as base, if this staging variation used a removal variation as its base."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["done"],"description":"Event type indicating successful completion."},"result":{"oneOf":[{"$ref":"#/components/schemas/ImageResult"},{"type":"array","items":{"$ref":"#/components/schemas/ImageResult"}}],"description":"Generated result images."}},"required":["event_type","result","render_id","variation_id","variation_type","timestamp","base_variation_id"]},"ImageResult":{"type":"object","properties":{"url":{"type":"string","description":"Original image URL."},"optimized_url":{"type":["string","null"],"description":"Optimized (compressed) version URL."},"thumbnail_url":{"type":["string","null"],"description":"Thumbnail version URL."}},"required":["url"]},"ErrorWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that failed."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that failed."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["error"],"description":"Event type indicating an error occurred."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["event_type","error_message","render_id","variation_id","variation_type","timestamp"]},"UpdateWebhookResponse":{"type":"object","properties":{"render_id":{"type":"string","description":"ID of the render that this variation belongs to."},"variation_id":{"type":"string","description":"ID of the variation that was updated."},"variation_type":{"type":"string","enum":["staging","removal","enhancement","daytodusk","multi-view-staging"],"description":"Type of variation that was updated."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["update"],"description":"Event type indicating a status update."},"variation_status":{"type":"string","enum":["queued","rendering","done","error","idle","deleted"],"description":"Current status of the variation."},"eta":{"type":"number","description":"Estimated time remaining for the variation to complete (epoch milliseconds timestamp)."}},"required":["event_type","variation_status","eta","render_id","variation_id","variation_type","timestamp"]},"AnalysisDoneWebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"Analysis ID."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["analysis_completion"],"description":"Event type indicating successful analysis completion."},"percentage_masked":{"type":"number","description":"Percentage of the image that was identified as furniture."},"result_url":{"type":"string","description":"URL of the analysis result image."}},"required":["event_type","result_url","id","percentage_masked","timestamp"]},"AnalysisErrorWebhookResponse":{"type":"object","properties":{"id":{"type":"string","description":"Analysis ID."},"timestamp":{"type":"number","description":"Event timestamp (epoch milliseconds)."},"event_type":{"type":"string","enum":["analysis_error"],"description":"Event type indicating analysis failure."},"error_message":{"type":"string","description":"Detailed error message explaining the failure."}},"required":["id","timestamp","event_type","error_message"]}}}} ``` --- # 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/endpoints.md?ask= ``` 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.