Skip to main content
const url = client.getMediaUrl(photoId, options?)
Synchronous — returns a URL string pointing to /api/media/{photoId} with your transform params as query string. On first access the server processes the image and caches the result permanently. Subsequent requests return the cached file.
This is the only SDK method that does not make a network request. It builds and returns a string immediately.

​
Parameters

​
photoId
string
required
UUID of the photo. Obtain it from getPhotos() or getCollection().
​
options
MediaUrlOptions
Optional transform options. Server defaults apply when omitted.

​
MediaUrlOptions

​
w
number
Target width in pixels (1–5000). Height scales proportionally unless h is also set.
​
h
number
Target height in pixels (1–5000). Width scales proportionally unless w is also set.
​
format
string
default:"webp"
Output format. One of webp, jpeg, or avif.
​
q
number
default:85
Quality from 1 (lowest) to 100 (highest).
​
fit
string
default:"cover"
Scaling mode when both w and h are provided.
ValueBehavior
coverCrops to fill the box exactly
containLetterboxes to fit within the box
fillStretches to fill the box exactly

​
Returns

A URL string, for example: 
https://panel.yourdomain.com/api/media/abc-123?w=800&format=webp&q=85

​
Examples

transforms.ts
// 800px wide at 75% quality
const thumb = client.getMediaUrl(photo.id, { w: 800, q: 75 })

// Square crop for a grid card
const square = client.getMediaUrl(photo.id, { w: 600, h: 600, fit: "cover" })

// AVIF for modern browsers
const avif = client.getMediaUrl(photo.id, { w: 1200, format: "avif", q: 80 })

// Open Graph image
const og = client.getMediaUrl(photo.id, { w: 1200, h: 630, fit: "cover" })

// No options — server defaults apply
const url = client.getMediaUrl(photo.id)

​
Caching

The server stores the transformed image after the first request. All subsequent calls with the same params skip processing entirely. 
Cache-Control: public, max-age=31536000, immutable

​
Pre-generated versions vs. getMediaUrl

SituationApproach
Standard grid / detail / download sizesphoto.versions.find(v => v.versionType === "webp_thumb")?.url
Custom size or cropclient.getMediaUrl(photo.id, { w: 400 })
AVIF outputclient.getMediaUrl(photo.id, { format: "avif" })
OG / social preview cropclient.getMediaUrl(photo.id, { w: 1200, h: 630, fit: "cover" })
Pre-generated URLs are always fastest for their target sizes. Use getMediaUrl only when the three built-in versions don’t cover your case.