Scene Virtual Try-On
Scene VTO places a product into a room or environment photo. You provide a scene image, a product image, and a text description (maskPrompt) of the target area where the product should be placed.
Specifying the Target Area
Provide a maskPrompt — either a short object name or a natural language instruction describing what to replace and where to place the product.
- Best for scenes with clearly identifiable objects or describable target areas
- Maximum length: 1,024 characters
Short prompts name an object in the scene to replace:
"armchair"→ replaces the armchair with the product"floor lamp"→ replaces the floor lamp with the product
Natural language prompts give more descriptive placement instructions:
"in the space across from the couch"→ places the product in the described area"replace the wooden chair next to the window"→ targets a specific object by context"place the product on the empty wall above the dresser"→ targets an empty area
Make Your First Request
Scene VTO - Sample Request
curl -L -X POST 'https://api-company-xyz.evolvestorefront.com/image-engine/vto/scene' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...' \
-d '{
"sourceImage": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
"productImage": "/9j/4AAQSkZJRgABAQEASABIAAD...",
"maskPrompt": "in the space across from the couch"
}'
Scene VTO - Sample Response
{
"success": true,
"data": {
"resultImage": "iVBORw0KGgoAAAANSUhEUgAA...",
"mimeType": "image/png",
"processingTime": 6.214
}
}
Tips for Best Results
tip
- Use clear, specific mask prompts (e.g.,
"the wooden chair"rather than"furniture") - Products with transparent or clean backgrounds produce better results
- Keep scene images well-lit and uncluttered for more natural composites
Error Handling
| Error Code | HTTP Status | Description |
|---|---|---|
VALIDATION_ERROR | 400 | Missing required fields (sourceImage, productImage, maskPrompt) |
INVALID_MASK_PROMPT | 400 | Mask prompt is empty or exceeds 1,024 characters |
IMAGE_TOO_LARGE | 400 | Image exceeds 3,072 pixels on its longest side |
INVALID_IMAGE | 400 | Unable to decode the base64 image data |
IMAGE_GENERATION_ERROR | 500 | Generation failed — retry the request |