--- title: Working with images description: Serve team badges, league logos and player photos straight from the BSD image proxy — no auth, cached at the edge. --- # Working with images Every entity in the API has an image at a predictable URL built from the same id the REST API gives you. No token, no extra lookups, aggressive caching. Full type list: [Image API reference](/docs/images/). ## URL patterns ``` https://sports.bzzoiro.com/img/// football (bare types) https://sports.bzzoiro.com/img//// other sports ``` ```html

``` The `` is the same numeric id the REST API returns — `team_id`, `league_id`, `player_id` and so on. ## Modifiers | Param | Effect | |---|---| | `?bg=transparent` | Removes the white background from the image edges — for cards and dark UIs | | `?sor=true` | Players only: serves a cut-out face-style photo when available, silently falls back to the regular photo otherwise | | `?sor=true&bg=transparent` | Both combined | ```html

``` Because `?sor=true` falls back silently, you can use it on every player image without checking availability first. ## Caching and fallbacks — what to expect - Images are cached server-side up to 30 days and browser-cached up to a year. Don't build your own image cache; hotlinking is the intended use. - An id that exists but has no image yet returns **204 No Content** (empty body) rather than 404 — render your own placeholder when the image fails to load: ```html

``` - A `null` or non-numeric id also returns 204, so templates that interpolate optional ids never break. - First-ever request for an image can take ~1 s (upstream fetch); every request after that is instant from cache. ## Sport-scoped types don't collide `/img/tennis/player/1207/` and `/img/player/1207/` are different namespaces — a tennis id never accidentally serves a football photo. Always use the sport prefix for non-football entities.