# Image URL contract

An image URL has the shape `<base>/img/<preset>/plain/<did>/<cid>`. `blobs.HydrateImageURL` builds proxy URLs from the owner's DID, blob CID and preset without resolving a PDS or making a network call. The AppView's base is configured by `IMAGE_PROXY_BASE_URL` (or its CDN override when configured). Tidepool uses `COVES_MEDIA_BASE_URL`, set to the `IMAGE_PROXY_BASE_URL` of its paired AppView. `content_full` is the full image preset; `content_preview` is used for previews.

The supported presets and their maximum or target dimensions are:

| Preset | Dimensions (px) | Fit | JPEG quality |
| --- | --- | --- | --- |
| `avatar` | 1000 × 1000 | cover | 85 |
| `avatar_small` | 360 × 360 | cover | 80 |
| `banner` | 640 × 300 | cover | 85 |
| `content_preview` | width up to 800, proportional height | contain | 80 |
| `content_full` | width up to 1600, proportional height | contain | 90 |
| `embed_thumbnail` | 720 × 360 | cover | 80 |

Output format depends on the source: PNG remains PNG; JPEG and WebP produce JPEG; GIF `content_full` serves the original GIF, while other GIF presets produce a JPEG of its first frame. The JPEG quality column applies only to JPEG output.

## AppView ownership and serving

Tidepool emits image URLs only for records indexed by its paired AppView. Another AppView's bridge uses that AppView's base URL. A blob resides on its author's PDS, so separate AppViews that index the same record can each serve it under their own host. Moderation decisions apply per AppView.

The proxy serves an owner DID and CID only while that pair has an active indexed blob reference. It checks moderation first and canonicalises the CID before block and reference checks. An unreferenced pair returns 404 with `Cache-Control: no-store`, including for cached images and matching `If-None-Match` requests. A reference lookup failure returns 503, including on cache hits and conditional requests.

## Delivery ordering and URL stability

If Tidepool delivers a federated image post before the paired AppView indexes its record from the firehose, a remote fetcher gets 404. Tidepool's readiness gate (T11) must probe each image URL before the first delivery and delay delivery briefly on 404, within a bounded budget. Some remote platforms do not retry a failed thumbnail fetch.

Tidepool stores these URLs in ActivityPub payloads. Renaming or reshaping a preset requires a redirect from the old URL from then on so previously delivered URLs continue to work.