Media transformation

The transform endpoint works for video and audio files as well as images. Same endpoint, same variant lifecycle: identical parameters return the same variant, processing runs asynchronously, and finished derivatives are stored next to the original (private files stay private; public files serve derivatives from the CDN).

Video — transcode

http

POST /v1/files/:id/transform

json

{ "format": "mp4", "height": 720 }

format — "mp4" (default) or "webm"
height — optional scale: 240, 360, 480, 720 or 1080 (width scales proportionally; omit for a no-resize copy/re-encode)

bash

curl -X POST https://app.apulodi.dev/v1/files/file_8f2b…/transform \
  -H "Authorization: Bearer $APULODI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"mp4","height":720}'

Returns 202 Accepted with the variant in pending; poll the variants endpoint or subscribe to the file.processed webhook event.

Video — poster frame

Extract a single JPEG frame — ideal for <video poster> and thumbnails:

json

{ "poster": true }

The default seek position is the first frame. The result is an image/jpeg variant labeled poster.

Audio — convert

json

{ "format": "mp3" }

Supported audio targets: "mp3", "m4a", "ogg", "wav". Useful to normalize a mixed-format library into one deliverable format (or to pull the audio track out of a video — the transcode of a video to an audio format strips the video stream).

Supported inputs

Type	Formats
Video	`video/mp4`, `video/webm`, `video/quicktime` (mov), `video/x-matroska` (mkv)
Audio	`audio/mpeg` (mp3), `audio/mp4` (m4a), `audio/wav`, `audio/ogg`, `audio/webm`, `audio/aac`, `audio/flac`

Limits & behavior

Source files up to 100 MB can be transformed.
Encoding is bounded by a function timeout — keep source clips short or use height-limited transcodes for larger inputs.
Identical parameters map to the same variant (idempotent); failed variants are retried automatically when re-requested.
Variants are billed against the project's file count/size quotas and bandwith is metered on download (same as originals).
Transformation parameters are validated per file type — sending image params to a video file returns a VALIDATION_ERROR.

← Multipart uploads

Webhooks →