Skip to main content
Let the user choose a casual outfit, a floral dress, or a navy dress while staying in the same session. Prepare an image for each look, register them at session creation, and switch the active source image when the user makes a choice.

​
1. Prepare a consistent set of images

The character in a white top and pink skirt
White top and pink skirt		The same character in a floral dress
Floral dress		The same character in a navy dress
Navy dress
The three example images show a white top with a pink skirt, a floral dress, and a navy dress. Normalize their aspect ratios and keep the character position and framing comparable. The pose, camera distance, and background will also change with the selected image, so consider them alongside the outfit. This switches to an image you have already prepared. A request to “wear a red dress” does not generate a new outfit image by itself. Your application can map a wardrobe button or tool call to an existing image ID.

​
2. Register the looks at session creation

This is a configuration fragment. Merge visual into the same avatar in your creation request, preserving its avatar_id, instructions, and voice settings. With several images, use default_source_image_id to choose the opening look. See Quickstart for a complete creation request.

​
3. Switch when the user chooses a look

Send this event through the current session’s control WebSocket:
Generate a new event_id for each request and show a switching state. session.updated confirms acceptance. Wait for session.update.done and match request_event_id to this request.
On completed, end the waiting state and inspect the new look in the video. On cancelled, the request did not complete and may have been superseded. On failed, show the failure and investigate its reason or error details. Let the result drive the selector state instead of announcing success as soon as a button is pressed.

​
4. Use the same pattern elsewhere

  • Locations: move between prepared indoor, street, and stage images.
  • Framing: offer a conversational portrait and a full-body performance view.
  • Virtual try-on: map a product card to its prepared outfit image and keep the UI selection in sync.
To switch when a user says “Show me the floral dress”, see Switch outfits with a tool call. The model selects an available choice, your application performs the same session.update, and the result returns to the conversation. Prepared table-supported and held images can also provide explicit product-support states; see Object interaction.

​
5. Check the next turn too

Do more than inspect the moment of the switch. Select the floral dress, allow an idle interval, and send another message. Check that the old outfit does not return. Each description should match its own image; Instructions should not make the white top permanent, and idle motion should not restate an old outfit. This changes the visual source for the same avatar without clearing the conversation. If a scene change also needs to reset an order, product selection, or task, handle that explicitly in your application.