Overview

The integration of Evolve Image Engine into your client-side application will differ depending on the technology you're using and customer experience needs. This page will walk you through some design and implementation considerations to help you get up and running. We will assume you're integrating with your e-commerce site, but the design and considerations would apply for native apps and other end-user applications.

User Experience Design

Where does Virtual Try-On appear?

Virtual Try-On is most commonly integrated into your product detail page (PDP). The specific placement depends on the VTO mode:

• Garment VTO: A "Try On" or "Virtual Try-On" button on apparel and footwear product pages, inviting the user to see how the item looks on them.
• Scene VTO: A "See in My Room" or "Place in Scene" button on furniture and home decor product pages, letting the user visualize the product in their own space.
• Surface VTO: A "Visualize Material" or "See This Finish" button on home furnishing, flooring, or wall covering product pages, letting the user see how a material looks applied to a surface in their own room.

The button should be prominent and placed near the product image or "Add to Cart" action, so it feels like a natural part of the shopping flow.

How does the user provide their photo?

Depending on the device and use case, consider supporting multiple input methods:

1. File upload — Let the user browse and select a photo from their device. Works on both desktop and mobile.
2. Device camera — On mobile devices, offer the option to take a photo directly. This is especially useful for Garment VTO where the user photographs themselves.
3. Pre-set model gallery — For Garment VTO, you may curate a set of model photos so users can quickly see how garments look without uploading their own photo.

How do you handle processing time?

Image generation typically takes 3–8 seconds. During this time, provide clear feedback to the user:

1. Show a loading spinner or progress indicator immediately after the user submits.
2. Display a message such as "Generating your virtual try-on..." to set expectations.
3. Consider disabling the submit button to prevent duplicate requests.

Displaying the result

Once the generated image is ready:

1. Show the composite image prominently, ideally at a similar size to the original product image.
2. Offer an option to download or share the result.
3. Provide a "Try Another" option so the user can experiment with different photos or products.
4. For Scene VTO, consider showing the original scene alongside the result for easy comparison.

Technical Flow

VTO Integration Flow

Encode Images

When the user selects an image, the file must be base64-encoded before being sent to the API. The base64 string should not include the data: URI prefix.

JavaScript

const fileToBase64 = (file) => {
    return new Promise((resolve, reject) => {
        const reader = new FileReader();
        reader.readAsDataURL(file);
        reader.onload = () => {
            // Remove the data URL prefix (e.g., "data:image/png;base64,")
            const base64String = reader.result.split(',')[1];
            resolve(base64String);
        };
        reader.onerror = (error) => reject(error);
    });
};

// Usage
const handleFile = async (file) => {
    try {
        const base64 = await fileToBase64(file);
        console.log(base64);
    } catch (error) {
        console.error('Error converting file:', error);
    }
};

TypeScript

const fileToBase64 = (file: File): Promise<string> => {
    return new Promise((resolve, reject) => {
        const reader: FileReader = new FileReader();
        reader.readAsDataURL(file);
        reader.onload = () => {
            // Remove the data URL prefix (e.g., "data:image/png;base64,")
            const base64String: string = (reader.result as string).split(',')[1];
            resolve(base64String);
        };
        reader.onerror = (error: ProgressEvent<FileReader>) => reject(error);
    });
};

// Usage
const handleFile = async (file: File): Promise<void> => {
    try {
        const base64: string = await fileToBase64(file);
        console.log(base64);
    } catch (error) {
        console.error('Error converting file:', error);
    }
};

Python

import base64

def file_to_base64(file_path):
    try:
        with open(file_path, 'rb') as file:
            file_content = file.read()
            base64_encoded = base64.b64encode(file_content)
            return base64_encoded.decode('utf-8')
    except Exception as e:
        print(f"Error converting file: {e}")
        return None

# Usage
base64_string = file_to_base64('path/to/your/file.jpg')
print(base64_string)

note

Images must be JPEG or PNG format and should not exceed 3,072 pixels on the longest side. Implement client-side validation to reject oversized images before making API calls.

Authentication

warning

Your client_id and client_secret values should be treated as sensitive values and should not be exposed to end users. The token generation call should be made server-side, where it won't be seen in the user's browser.

tip

The access token is valid for 1 hour and can be reused as many times as needed within the time limit. Cache this token server-side instead of generating a new one every time a VTO request is made.

Once a token is obtained, pass it in the Authorization header of each API call. See Generate Access Token for details.

Invoke the API

With a valid token, call the appropriate endpoint from your server-side code:

• Garment VTO: POST /vto/garment — see Garment Virtual Try-On API
• Scene VTO: POST /vto/scene — see Scene Virtual Try-On API
• Surface VTO: POST /vto/surface — see Surface Virtual Try-On API

Your server acts as a proxy between the client and the Image Engine API, keeping credentials secure while forwarding the base64-encoded images and returning the result.

Decode and Display the Result

The API returns the generated image as a base64-encoded string. Convert it back to a displayable image on the client:

JavaScript

// Create a data URL from the API response
const dataUrl = `data:${response.data.mimeType};base64,${response.data.resultImage}`;
document.getElementById('result-image').src = dataUrl;

TypeScript

// Create a data URL from the API response
const dataUrl: string = `data:${response.data.mimeType};base64,${response.data.resultImage}`;
(document.getElementById('result-image') as HTMLImageElement).src = dataUrl;

Python

import base64

# Decode and save the result image
result_bytes = base64.b64decode(response['data']['resultImage'])
with open('result.png', 'wb') as f:
    f.write(result_bytes)

Response Size Considerations

warning

The result image is returned as inline base64 data, which can produce responses up to approximately 5.5 MB. Ensure your HTTP client and server can handle large response bodies. Consider:

• Setting appropriate request timeout values (10+ seconds recommended)
• Allocating sufficient memory for base64 decoding
• Compressing or resizing the result before sending it to the end user's browser

Error Handling

Implement error handling for the three response categories:

• 400 (Bad Request) — Validation errors. Check the error.code field and display a user-friendly message. These are not retryable.
• 401 (Unauthorized) — Token expired or invalid. Refresh the access token and retry.
• 500 (Internal Server Error) — Generation failure. These may be transient — implement a retry with exponential backoff (1-2 retries max).

Error Response Format

{
    "success": false,
    "error": {
        "message": "A human-readable description of the error",
        "code": "ERROR_CODE"
    }
}