docs menu

Media

Each project has a media library. A file is stored once, by content: uploading the same bytes again returns the existing media id. Documents point to media by id, in image and file fields and in rich text.

Upload#

Send the raw bytes to POST /p/<project>/v1/media, with the file type in content-type:

bash
curl https://api.galerne.cloud/p/acme/v1/media?filename=harbour.jpg&alt=Harbour%20at%20dawn \
  -H "Authorization: Bearer gal_…" \
  -H "content-type: image/jpeg" \
  --data-binary @harbour.jpg
QueryWhat it sets
filenameThe original file name
altDefault alt text, used when a field leaves its own alt empty
titleA title for the library

To keep a media id from another system, as imports do, send it in the x-galerne-media-id header.

The answer is the media record with its url. It is 201 for a new file and 200 with "existed": true when the same bytes were already there. Files can be up to 200 MB. Uploads need the media_upload right: contributors, editors and admins, and agents with those roles.

With the client: await galerne.uploadMedia(file, { filename: 'harbour.jpg', alt: 'Harbour at dawn' }). From the CLI: galerne media upload harbour.jpg --alt "Harbour at dawn".

Agents use upload_media with a public https URL or base64 data. Galerne fetches URLs itself, from public addresses only, with a timeout and a size cap.

Use it in a document#

json
{ "cover": { "asset": "m_7Qk2…", "alt": "Harbour at dawn", "hotspot": { "x": 0.5, "y": 0.4 } } }

In rich text, as Markdown: ![Harbour at dawn](media:m_7Qk2…).

Describe it#

update_media (or PATCH /p/<project>/v1/media/<id>) sets alt, title, caption, credits, license, tags and expiresAt. get_media returns a file's details and the documents that use it. list_media searches the library by text, tag and type, and unused: true finds files no document uses.

replace_media (PUT /p/<project>/v1/media/<id>) swaps the bytes of a file and keeps its id, so every document that uses it shows the new file. delete_media deletes a file, and is refused while documents use it; the error lists them.

Serve and transform#

Files are served at:

https://api.galerne.cloud/p/<project>/media/<id>
https://api.galerne.cloud/p/<project>/media/<id>/<any-file-name>

The second form puts a readable name in the URL; the name is ignored. Files are public to anyone with the URL, and media ids are long and random. Responses carry an etag and cache-control: public, max-age=3600, s-maxage=86400, and the CDN caches them.

Images (PNG, JPEG, WebP, AVIF, GIF) take transform parameters:

ParameterValuesWhat it does
w1 to 4000Width in pixels
h1 to 4000Height in pixels
fitcover (default), contain, inside, outside, fillHow the image fits w × h
fmwebp, avif, jpeg (or jpg), pngOutput format
html
<img src="https://api.galerne.cloud/p/acme/media/m_7Qk2…?w=1200&fm=webp" alt="Harbour at dawn" width="1200">

cover fills the box and crops, centred on the most detailed area. outside does the same without enlarging an image smaller than the box. contain and inside fit the whole image in the box. fill stretches it to the exact size. The API answers with the resized image, which the CDN caches. With the client: galerne.mediaUrl(id, { w: 1200, fm: 'webp' }). In Next.js, galerne.Image from the Next.js kit builds the srcset, sets width and height, and keeps the hotspot in frame with object-position.

Values out of range answer 400. SVG files are served as they are, with a strict content security policy so they cannot run scripts.

Video and large files#

Media URLs answer Range requests with 206 Partial Content, so browsers can seek in video and audio without downloading the whole file. A range past the end answers 416.

Metering#

Bytes served count toward the CDN bandwidth of your plan, and stored files toward media storage. The limits page lists both per plan.