Surface Virtual Try-On

Surface VTO applies materials and textures to surfaces in a room or scene photo. You provide a scene image, a material swatch/sample image, and a text description (maskPrompt) of the target surface where the material should be applied.

Use cases include visualizing fabric on furniture, tile on floors, wood paneling on walls, paint finishes, wallpaper patterns, and stone surfaces like marble countertops.

Material Classes

Each request can optionally include a materialClass that tells the system what type of material is being applied. This enables material-specific generation for more realistic results. If omitted, the system uses a general-purpose material application approach.

Material Class	Description	Examples
`FABRIC`	Fabric and textiles	Upholstery, leather, vinyl, cushion fabric
`TILE`	Tile surfaces	Floor tile, wall tile, backsplash
`WOOD`	Wood surfaces	Hardwood flooring, wood planks, paneling
`PAINT`	Paint finishes	Wall paint, painted surfaces
`WALLPAPER`	Wall coverings	Patterned wallpaper, textured wall coverings
`STONE`	Stone surfaces	Marble, granite, flagstone, countertops

tip

Specifying the correct material class improves result quality. For example, using FABRIC for upholstery ensures the material follows the contours and folds of the furniture, while TILE maintains a consistent grid pattern with realistic grout lines.

Specifying the Target Surface

Provide a maskPrompt — a text description of the surface in the scene to apply the material to.

Maximum length: 1,024 characters

Object-based prompts name a surface or object:

"sofa cushions" → applies material to the sofa cushions
"the floor" → applies material to the floor
"headboard" → applies material to the headboard

Descriptive prompts provide more context:

"the wall behind the bed" → targets a specific wall
"the kitchen backsplash" → targets the backsplash area
"the hardwood floor in the living room" → targets a specific floor area

Make Your First Request

Send a POST request to the /vto/surface endpoint with a scene photo (sourceImage), a material swatch (materialImage), a target surface description (maskPrompt), and optionally a materialClass.

Surface VTO - Sample Request
curl -L -X POST 'https://api-company-xyz.evolvestorefront.com/image-engine/vto/surface' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6...' \
    -d '{
        "sourceImage": "/9j/4AAQSkZJRgABAQAAAQABAAD...",
        "materialImage": "/9j/4AAQSkZJRgABAQEASABIAAD...",
        "materialClass": "FABRIC",
        "maskPrompt": "sofa cushions"
    }'

Surface VTO - Sample Response
{
    "success": true,
    "data": {
        "resultImage": "iVBORw0KGgoAAAANSUhEUgAA...",
        "mimeType": "image/png",
        "processingTime": 5.947
    }
}

Understanding the Response

Field	Description
`resultImage`	Base64-encoded image of the scene with the material applied to the target surface
`mimeType`	The format of the result image (e.g., `image/png`)
`processingTime`	Time in seconds taken to generate the image

To display the result, decode the base64 string back to an image. For example, using the command line:

Decode result image
echo "<resultImage value>" | base64 -d > result.png

Tips for Best Results

tip

Use a clean, well-lit material swatch photo with consistent texture and minimal shadows
Be specific with mask prompts (e.g., "the floor tiles" rather than "the floor")
Specifying materialClass generally improves output quality
Larger, more visible surfaces in the scene produce more visually impactful results
Keep scene images well-lit and uncluttered for more natural composites

Error Handling

If the request fails, the response will include an error code and message:

Error Response
{
    "success": false,
    "error": {
        "message": "Invalid material class: METAL. Must be one of: FABRIC, TILE, WOOD, PAINT, WALLPAPER, STONE",
        "code": "INVALID_MATERIAL_CLASS"
    }
}

Error Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Missing required fields (sourceImage, materialImage, maskPrompt)
`INVALID_MATERIAL_CLASS`	400	`materialClass` is not one of the valid enum values
`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

Material Classes​

Specifying the Target Surface​

Make Your First Request​

Understanding the Response​

Tips for Best Results​

Error Handling​

API Reference​