# Media

> Upload images and files, describe them, resize and convert images with URL parameters, and stream video with Range requests.

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
```

| Query | What it sets |
|---|---|
| `filename` | The original file name |
| `alt` | Default alt text, used when a field leaves its own alt empty |
| `title` | A 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:

```text
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:

| Parameter | Values | What it does |
|---|---|---|
| `w` | 1 to 4000 | Width in pixels |
| `h` | 1 to 4000 | Height in pixels |
| `fit` | `cover` (default), `contain`, `inside`, `outside`, `fill` | How the image fits `w` × `h` |
| `fm` | `webp`, `avif`, `jpeg` (or `jpg`), `png` | Output 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](/docs/nextjs.md#components) 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](/docs/limits.md) page lists both per plan.
