> ## Documentation Index
> Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Avatar Background

> Download the optional 16:9 Avatar background from Spatius Studio and render it behind AvatarKit in your app.

An **Avatar Background** is an optional image generated with a Personal Avatar. It is a separate client-side asset, not part of the avatar assets or Motion Server flow.

## Mental model

Treat the background and Avatar as one fixed stage:

* The background is the **16:9 master stage**.
* The Avatar keeps the same position and scale inside that stage.
* Other aspect ratios crop a window from the same stage.

<Frame>
  <img src="https://mintcdn.com/spatius/5L7C3vMPuvGsb0G_/images/avatar-background-stage.jpg?fit=max&auto=format&n=5L7C3vMPuvGsb0G_&q=85&s=a6c58ab10bc4cd50ac239cd52bc167c2" alt="Avatar rendered on a 16:9 background stage" width="1536" height="864" data-path="images/avatar-background-stage.jpg" />
</Frame>

The downloaded asset is that stage without the Avatar:

<Frame>
  <img src="https://mintcdn.com/spatius/5L7C3vMPuvGsb0G_/images/avatar-background-asset.jpg?fit=max&auto=format&n=5L7C3vMPuvGsb0G_&q=85&s=c74442adab78522e40d210069e3b0842" alt="Extracted 16:9 Avatar background asset" width="1536" height="864" data-path="images/avatar-background-asset.jpg" />
</Frame>

## Get the background asset

<Steps>
  <Step title="Open the Avatar in Spatius Studio">
    Go to [Spatius Studio](https://app.spatius.ai), open the Personal Avatar, and find the **Background** card below the preview.
  </Step>

  <Step title="Download the background">
    Select **Download**. The image is the 16:9 master stage without the Avatar.
  </Step>

  <Step title="Add it to your app">
    Bundle the image with the client or upload it to infrastructure your application controls.
  </Step>
</Steps>

<Note>
  `AvatarManager` loads avatar assets, but not this background image. If your app supports multiple Avatars, map each `avatar-id` to its background in your application.
</Note>

## Render the two layers

Place a transparent Avatar view above the background inside the same stage:

```text theme={null}
Display window (clips overflow)
└── 16:9 stage
    ├── Background image
    └── Transparent Avatar view
```

Both layers must fill the stage and share the same coordinate system. This composition is entirely client-side and works with every integration.

Implementation guides: [Web](/sdk-reference/web-sdk/reference#render-over-an-avatar-background) · [iOS](/sdk-reference/ios-sdk/api-reference#render-over-an-avatar-background) · [Android](/sdk-reference/android-sdk/api-reference#render-over-an-avatar-background) · [Flutter](/sdk-reference/flutter-sdk/api-reference#render-over-an-avatar-background)

## Crop for other aspect ratios

Use aspect-fill and center-crop for square, portrait, or custom containers. Keep the 16:9 stage centered and clip its overflow; do not stretch the background or move the Avatar independently.

<Warning>
  The Avatar and background must be transformed together. Independent scaling or positioning breaks their spatial relationship.
</Warning>

## Practical rules

* Store the image as a normal Web, iOS, Android, or Flutter application asset, or serve it from your CDN.
* Preload it while the Avatar loads so both layers can appear together.
* Switch the Avatar and its mapped background in the same visual update.
* If the image is unavailable, fall back to an application-provided scene without blocking AvatarKit.

## Next steps

<CardGroup cols={2}>
  <Card title="Avatar" icon="user" href="/concepts/avatar" />

  <Card title="Client Lifecycle" icon="play" href="/concepts/lifecycle" />
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.