Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

How to add a Virtual Try-On to an e-commerce app

Overview

Letting shoppers see a garment on themselves, rather than on a model, is one of the most direct uses of the Virtual Try-On feature of the Image Editing API. This tutorial shows how to build that experience in a native iOS app: the shopper picks a product, takes a selfie (or chooses a full-body photo), enters their height, and gets back a photo of themselves wearing the piece.

The screenshots and code samples come from a SwiftUI reference implementation; the same approach applies to any mobile or web app.

What the flow looks like

  1. The shopper opens a product and taps Try on me.

  2. They provide a photo of themselves, either from the photo library or with an in-app camera that fires after a three-second countdown.

  3. They enter their height in centimetres.

  4. They tap Generate try-on. A single call to the Image Editing API returns the try-on image.

  5. They can switch to another product and generate again with the same photo and height.

1. Pick a product

2. Add a photo and height

3. Generate the try-on

The whole flow is one API call per product. Everything else (camera, countdown, height validation, image preparation) runs on the device. The photo and height are kept in memory only and are never persisted to disk.

Before you start

You need an iPhone running iOS 17 or later (the Simulator works for everything except the camera) and a Photoroom API key. If you don't have one yet, here are the steps to create yours. Store the key in the device Keychain, never in the app bundle or in logs.

Use Sandbox mode while you develop: prepend sandbox_ to your API key and calls are free (results are watermarked).

How it works

Step 1: Take the selfie

A good try-on starts with a good input photo: one person, full body, good lighting, clothing clearly visible. A small dedicated camera screen, rather than the system picker, helps the shopper get there:

  • It defaults to the front camera, so a shopper can frame themselves, and offers a flip button.

  • The shutter starts a three-second countdown so the shopper has time to step back and stand naturally. Each tick is also announced to VoiceOver. The countdown can be cancelled, and is cancelled automatically when the app becomes inactive.

  • The capture uses the .photo session preset with photoQualityPrioritization = .speed, which is plenty for an upload that will be downscaled anyway, and keeps the shutter feeling instant.

  • The front-camera photo is captured mirrored, so that the review screen matches what the shopper saw in the preview.

  • After capture, a Retake / Use photo review screen lets the shopper check their pose before anything is uploaded.

Countdown

Review before upload

Alternatively, Choose a photo opens a PhotosPicker for an existing full-body photo. Both paths end up calling model.setPerson(image).

Step 2: Ask for the shopper's height

Height is the one piece of information the photo cannot provide: the same person can fill the frame from close up or far away, so the model has no reliable scale. Telling the API the shopper's height gives it a reference for garment length and drape.

Treat height as required, validated as a whole number between 50 and 250 cm, and only enable Generate try-on once both a photo and a valid height are present:

A detail worth copying: use a UITextField configured once with keyboardType = .numberPad, autocorrection, predictions and Writing Tools turned off, and an empty input-assistant bar. Numeric entry never needs the predictive-text UI, and configuring the traits before the field becomes first responder avoids keyboard flicker.

Changing the height, the photo, or the garment should cancel any in-flight request and clear the previous result, so a displayed image always corresponds to the inputs on screen.

Step 3: Prepare the images for upload

Before the API call, both the selfie and the product image go through the same preparation, on a dedicated background queue so the UI never stalls:

  • decode with CGImageSourceCreateThumbnailAtIndex and kCGImageSourceCreateThumbnailWithTransform, which bakes in the EXIF orientation (a selfie taken in portrait would otherwise arrive sideways);

  • downscale to at most 1,400 pixels on the longest edge;

  • draw onto an opaque white canvas, which strips any alpha channel and metadata;

  • encode as JPEG at quality 0.9.

This keeps uploads small (typically a few hundred kilobytes) without affecting the result, since the output resolution is decided by the API, not by the input.

Step 4: Call the Image Editing API

The try-on is a single POST /v2/edit request. The product image is the main imageFile, and the shopper's photo is passed as the custom model with virtualModel.model.custom.imageFile. The prompt in virtualModel.prompt is assembled from three parts: instructions to keep the shopper's identity, pose, background and framing unchanged; the shopper's height; and, when your catalogue has them, the garment's measurements (length, flat chest width, shoulder width and sleeve length, in cm). Together they give the model a scale for the person and for the garment, so the hem and sleeves land in a plausible place. The equivalent curl call is:

And in Swift, with a small multipart helper:

A few points about these parameters:

  • No scene or pose override. The Virtual Try-On feature accepts virtualModel.scene and virtualModel.pose, but this flow deliberately omits them: the goal is to show the garment on the shopper as they are, in their own photo, so the prompt asks to preserve the original background and pose instead.

  • removeBackground=false keeps the shopper's own background in the output. The Virtual Try-On documentation also recommends referenceBox=originalImage when keeping the background; add it if you notice the framing changing.

  • Height is guidance, not a measurement. It helps the model choose a plausible garment length and drape; it does not guarantee a physically exact fit. Keep the wording in the prompt explicit about not resizing the person.

  • Garment measurements are guidance too. Take them from your size chart and spell out how each one is defined (flat width, not circumference; length from the high shoulder point, excluding the collar), so the model interprets the numbers the way you intend. If a product has no measurements, simply leave this part of the prompt out rather than inventing values.

  • export.format=webp keeps the download small on mobile networks; UIImage decodes it directly.

  • To request a 2K output, add virtualModel.quality=advanced. This is an Enterprise plan option; without it you get the default 1K output.

The response body is the image itself. Check the status code and the Content-Type before decoding:

Using an ephemeral URLSession is a small but worthwhile privacy measure: the shopper's photo and the generated image never touch the on-disk URL cache.

Step 5: Show the result and let the shopper keep shopping

Run the request in a Task tagged with a revision ID, so that a late response from a cancelled request can never overwrite a newer result. While the request is in flight, show the shopper's photo blurred under an "Applying your look" card that repeats the height being used, with a Cancel generation button. Decode the returned image at up to 4,096 pixels for display and the save/share screen.

While generating

Result

Because the photo and height live in the view model, the shopper can expand the product panel and pick another piece: reuse the prepared selfie and the same prompt structure and make one more API call. Backgrounding the app or closing the fitting room should cancel any request in progress.

Handling errors

Map HTTP status codes to short, actionable messages:

Set the request timeout to 180 seconds: Virtual Try-On is a generative feature and can take longer than a plain background removal, especially at higher output resolutions.

Adapting the flow to your app

  • Your own catalogue. Flat packshots on a clean background work best as the product image, and you can pass extra angles with virtualModel.additionalProductImages[].imageFile. If you have size-chart data, attach it to each product so it flows into the prompt.

  • Remember the shopper. This tutorial keeps the photo and height in memory for the lifetime of the view. In a real app you may want to store them (with consent) so a returning shopper can try on new arrivals in one tap.

  • Server-side calls. Shipping an API key inside a mobile app exposes it to anyone who inspects the binary. For production, move the request behind your own backend and keep the camera, height input and image preparation on the device. The API call is a plain multipart HTTP request and translates directly to any language; see Code Samples.

  • A studio look instead of the shopper's photo. If you want a polished editorial result rather than the shopper's own background, set virtualModel.scene.preset.name and virtualModel.pose=standing, and drop the "preserve background and framing" wording from the prompt. The Virtual Model page lists the available scenes and poses.

Cost per try-on: 1 Image Editing API call per product. Taking a new photo or changing the height does not cost anything until the shopper taps Generate try-on again.

Book a demo

If you're interested to use this feature, feel free to contact our team to book a demo.

Book a demo

Going further

  • Feature reference: Virtual Try-On, Virtual Model.

  • Related tutorial: How to create listing images for clothing and apparel.

Last updated

Was this helpful?