Skip to main content
An Avatar Background is an optional visual companion asset for a Personal Avatar. It is generated from the final photo used to create the Avatar and is intended to be rendered behind the Avatar in your application. The background does not change the Avatar’s 3DGS assets, does not change Motion Server behavior, and does not affect motion data. It is a separate image layer that your client app can display behind the AvatarKit rendering surface.

​
Mental model

Treat the background and the Avatar as one fixed stage:
  • The background is the 16:9 master stage.
  • The Avatar keeps the same position and scale within that stage.
  • Other view sizes are display windows cropped from the same stage.
Avatar rendered on a 16:9 background stage
The extracted background asset is the same stage without the Avatar:
Extracted 16:9 Avatar background asset

​
Get the background asset

The background is available for a Personal Avatar when one was generated during Avatar creation.
1

Open the Avatar in Spatius Studio

Go to Spatius Studio, open the Personal Avatar, and find the Background card below the preview.
2

Download the background

Select Download in the Background card. The downloaded image is the 16:9 master stage without the Avatar.
3

Add it to your app

Bundle the image with the client or upload it to infrastructure that your application controls.
AvatarManager.load() loads avatar assets, but it does not download the separate background image. If your app supports multiple Avatars, keep an application-level mapping from each avatar-id to its background asset.

​
Add it to your app

Build the visual as two layers inside the same 16:9 stage:
The background fills the stage first. AvatarKit then renders the Avatar in a transparent view above it. Both layers must fill the same stage and use the same coordinate system. This composition is entirely client-side. It works the same way with Direct Mode Integration, Backend Mode Integration, and Platform Integrations; it does not change the Motion Server connection or motion data flow. For implementation examples, see Web, iOS, Android, or Flutter.

​
Display windows

Use the 16:9 background as the only master image. For square, portrait, or custom containers, crop the visible window from the same stage instead of stretching the image. The Avatar layer and the background layer should share the same container coordinate system. When the container ratio changes, do not move or scale the Avatar independently to “fix” the crop. To size the 16:9 stage so it covers a custom display window, use the larger of the horizontal and vertical scale factors:
Center the stage in the display window and clip the overflow.
Do not stretch, squeeze, or re-center the 16:9 background to match the container. That breaks the spatial relationship between the Avatar and the background.

​
Loading and switching

  • Preload the background while AvatarManager.load() loads the Avatar so the two layers can appear together.
  • When switching Avatars, update the Avatar and its mapped background as one visual change.
  • If an Avatar has no background, or the image fails to load, use a solid color or an application-provided fallback.
  • A background loading failure should not block AvatarKit initialization or the Motion Server connection.

​
What not to do

  • Do not use a separate background position for each device ratio.
  • Do not zoom or move the Avatar when switching from 16:9 to 1:1 or 9:16.
  • Do not use the background asset as part of the avatar assets bundle. Load it as a normal image layer in your app.
  • Do not expect the background to preserve physical contact between the original person and nearby objects perfectly.

​
Source image limits

The background is generated from a photo that originally contained the person. It works best when the person and background are visually related but not strongly physically coupled. Avoid depending on the background for cases where the original photo must preserve exact contact details, such as:
  • the person pressing into a sofa or chair
  • visible body shadows that must line up exactly
  • hands or arms resting on a table
  • clothing or hair occluding detailed background objects
In those cases, the extracted background can still be useful, but the reconstructed contact area may not look identical to the original photo.

​
Next steps

Avatar

Understand how Avatar IDs and avatar assets work.

Client Lifecycle

See where the Avatar is loaded and rendered in your app.

Demo projects

Explore complete client implementations.