# Hosting Pictures • Aivi Docs

> Where to put the pictures for widgets and Live Activities so every phone can load them, with step-by-step setups for Cloudflare R2 and the Home Assistant www folder.

Source: https://docs.getaivi.app/guides/hosting-pictures/

Several templates can show a picture from a URL: a [Switchboard](https://docs.getaivi.app/widget-templates/#switchboard-template) tile, the [Showcase](https://docs.getaivi.app/widget-templates/#showcase-template) and [Remote](https://docs.getaivi.app/widget-templates/#remote-template) widgets, and the [Remote](https://docs.getaivi.app/templates/#remote-template) Live Activity. Aivi never downloads that picture: each phone showing it fetches it on its own, without your credentials. So the picture has to live somewhere every phone can reach, from anywhere, over `https://`. This page shows how to prepare a picture and two ways to host it: a free [Cloudflare R2](#cloudflare-r2) bucket, which we recommend, and the [Home Assistant `www` folder](#home-assistant-www-folder).

## What a picture URL needs

Each phone downloads the picture, shrinks it, and keeps it. For that to work, the URL has to meet these rules:

- **Public `https://`, reachable from anywhere.** A phone away from home, or a family member’s phone, fetches the same URL. A LAN address such as `http://192.168.1.20/...` or `homeassistant.local` won’t load there.
- **Stable.** The URL must keep working. Links that expire, such as signed storage URLs or tokenized camera snapshots, stop loading after a while.
- **Small.** In PNG, JPEG, HEIC, WebP, or GIF. A tile’s picture (an action’s `image`) can be at most 512 pixels on a side and 256 KB; any other at most 2048 pixels and 1 MB, though 1024 pixels is plenty. Anything larger is refused, and the widget shows the gradient, the symbol, or the icon instead. A URL that fails isn’t tried again for 30 minutes.
- **A new URL for a new picture.** The phone trusts a picture for 24 hours. To change it sooner, change the URL, for example `dog-cam.jpg?v=2` or `dog-cam-2.jpg`.
- **Not right away.** The Aivi app fetches pictures when it opens, after it syncs, and in the background a few times a day; a widget also fetches missing ones on its next update. Until then, it shows the gradient, the symbol, or the icon.
- **Short.** Image URLs count toward the 4 KiB content limit, so a short domain and file name leave more room for everything else.

Pictures don’t show on every surface. Lock Screen and Apple Watch widgets, the tinted and clear Home Screen styles, the Always-On display, and a widget that hides its content on a locked phone show the icon or symbol instead. A Live Activity shows its picture wherever it has room for one.

Anyone who knows the URL can open the picture, so only host pictures you don’t mind being public.

### Prepare the file

Most photos are far larger than you need. On a Mac, `sips` resizes a photo so its longer side is 512 pixels, and saves it as a JPEG (use `-Z 1024` for a widget’s main picture):

```bash
sips -Z 512 -s format jpeg -s formatOptions 80 photo.jpg --out dog-cam.jpg
```

It also reads iPhone `.heic` photos. With [ImageMagick](https://imagemagick.org/) on any platform, the same is:

```bash
magick photo.jpg -resize '512x512>' -quality 80 dog-cam.jpg
```

A 512-pixel JPEG at this quality is usually well under 100 KB. Check the size before you upload it; if it’s over 256 KB, lower the quality.

## Cloudflare R2

[Cloudflare R2](https://developers.cloudflare.com/r2/) is object storage with a free monthly allowance: 10 GB of storage, 1 million write operations (such as uploads), and 10 million read operations. Downloads (egress) are free. A handful of thumbnails fetched by a few phones stays far inside it.

1. Sign in to the [Cloudflare dashboard](https://dash.cloudflare.com/), or create a free account, and open **Storage & databases** > **R2** > **Overview**. The first time, complete the checkout to add R2 to your account. It includes the free monthly allowance, and you’re billed only for usage beyond it.

2. Select **Create bucket**, give it a name such as `aivi-pictures` (lowercase letters, numbers, and hyphens), and select **Create bucket**. The default location and storage class are fine.

3. Make the bucket public. In the bucket, open **Settings**. Under **Public Development URL**, select **Enable**, type `allow` to confirm, and select **Allow**. The bucket’s public URL, on `r2.dev`, appears there.

   If you have a domain on Cloudflare, connect it instead: under **Custom Domains**, select **Add**, enter a subdomain such as `pictures.example.com`, select **Continue**, and then **Connect Domain**. See [Custom domain or r2.dev](#custom-domain-or-r2dev).

4. Back in the bucket, select **Upload** and drag in your prepared picture.

5. Put the public URL and the file name together, and use it as the tile’s `image.url`:

   ```json
   "image": {
     "url": "https://pictures.example.com/dog-cam.jpg",
     "alt": "The dog in the hallway"
   }
   ```

   Open the URL in a private browser window first: if the picture shows there, the phone can load it too.

To replace a picture, upload the new file under a new name, or keep the name and change the version in your payload (`dog-cam.jpg?v=2`). Either way, the phone loads it at the next sync.

### Custom domain or r2.dev

Cloudflare describes the `r2.dev` URL as meant for development: it is rate-limited, and Cloudflare recommends a custom domain for production. A personal widget is a light load: each phone fetches a picture about once a day, so `r2.dev` is fine for a home setup. If you already have a domain on Cloudflare, connect it anyway: the URL is shorter, it’s yours, and Cloudflare can cache the pictures. The domain must be a zone in the same Cloudflare account as the bucket.

## Home Assistant www folder

Home Assistant serves the files in its `www` folder at `/local/`, without asking for a login. That makes it a quick place for a few pictures, but only if your Home Assistant is reachable from the internet over `https://`: with [Home Assistant Cloud](https://www.home-assistant.io/docs/configuration/remote/) remote access, or your own setup such as a reverse proxy with a certificate. If your Home Assistant is only reachable at home (or only over a VPN), the picture won’t load on a phone away from it; use [Cloudflare R2](#cloudflare-r2) instead.

1. Create a folder named `www` inside your configuration folder (`/config`), for example with the File editor or Samba add-on. If the folder is new, restart Home Assistant once so it starts serving it.

2. Put your prepared picture in it, for example `/config/www/aivi/dog-cam.jpg`.

3. Build the URL from your public Home Assistant address and the path below `www`, with `/local/` in front:

   ```json
   "image": {
     "url": "https://ha.example.com/local/aivi/dog-cam.jpg?v=1",
     "alt": "The dog in the hallway"
   }
   ```

   Open it in a private browser window on mobile data to check that it loads away from home.

Anyone who knows a `/local/` URL can open that file, so keep only pictures you would share in `www`. When you replace a file, bump the version (`?v=2`) in the payload so phones fetch the new one.

Don’t forward an entity’s `entity_picture` as is. It is usually a relative, authenticated, or tokenized address that changes over time, so phones can’t load it. Copy the picture into `www` or a bucket and use that URL.

## Other hosts

Any static host works if the URL is public `https://` and stays the same: a web server you already run, another object storage service with public reads, or your own website. Avoid links that expire: signed or presigned storage URLs, camera snapshot links with a token, and share links that need a login all stop working, and the tile falls back to its gradient or symbol.
