API documentation
Llumi Cut is an HTTP service. You upload media, send a JSON timeline and download the result. This page summarises the fields; the complete, validated schema is at /openapi.json on every installation.
Authentication
Each installation has its own key. Send it on every /v1 route:
Authorization: Bearer <your-key>Flow
- Upload each file with
POST /v1/assets?kind=image|video|audioand the file as the binary body. It returns{"id": "…"}. - Queue the edit with
POST /v1/rendersand the timeline as JSON. Use theIdempotency-Keyheader so a retry doesn't create a second render. - Poll
GET /v1/renders/{id}untilstatusiscompleted, then download each file fromresult.files.
Endpoints
| Method | Path | What it does |
|---|---|---|
| GET | /health | Service status |
| POST | /v1/assets?kind=image|video|audio | Uploads a binary file and returns its ID |
| POST | /v1/renders | Validates the timeline and queues it |
| GET | /v1/renders | Latest 100 renders |
| GET | /v1/renders/{id} | Status, progress, events and errors |
| POST | /v1/renders/{id}/cancel | Cancels a queued or running render |
| POST | /v1/renders/{id}/retry | Retries a stopped render |
| DELETE | /v1/renders/{id} | Deletes a stopped render and its files |
| GET | /v1/renders/{id}/files/{name} | Downloads an output |
| POST | /v1/maintenance/purge?older_than_days=N | Deletes stopped renders older than N days |
Timeline
Only title, duration and clips are required. The shot durations must add up to duration.
| Field | Values |
|---|---|
duration | 3–600 s |
width · aspect | 640, 1280 or 1920 (long side) · 16:9, 9:16, 1:1 |
fps | 24 or 30 |
background | Colour of the letterbox bars, #RRGGBB |
transition · transition_duration | cut, fade, fadeblack, fadewhite, dissolve, slideleft, slideright, wipeleft, wiperight, smoothleft, smoothright, circleopen, circleclose · 0.1–2 s |
image_motion | none, zoom_in, zoom_out, pan_left, pan_right, auto |
fade_in · fade_out | Fade of the whole video and its sound, 0–5 s |
audio_asset_id · pauses | Optional main song and up to ten pauses of digital silence |
Shots (clips[])
| Field | Values |
|---|---|
asset_id · duration | Image or video · up to 60 s |
trim_start · speed | Start second in the source · 0.25–4 |
volume | The clip's own sound, 0–2 (0 mutes it) |
fit | contain (with bars) or cover (fills by cropping) |
freeze · motion | Freezes the first frame · Ken Burns movement |
effects | Up to six of grayscale, sepia, vintage, noir, warm, cool, blur, sharpen, vignette, invert, mirror, flip |
brightness · contrast · saturation | −0.5–0.5 · 0.3–2 · 0–3 |
transition · transition_duration | Transition from the previous shot |
Sound (audio_tracks[])
asset_id, start, trim_start, duration, volume (0–2), fade_in, fade_out, loop and duck. A track with duck: true drops by about 10 dB while the song, a voice or a clip's sound is playing.
Titles (texts[])
text (up to five lines), start, end, position (nine positions) or x/y as fractions of the frame, size, color, outline_color, outline, box, box_color, box_opacity, font, bold, italic and animation (none, fade, slide_up, slide_left, pop, typewriter).
Layers (overlays[])
asset_id (image or video), start, end, position or x/y, width, height (with both, the box is filled: split screen and grids), margin, opacity, trim_start, volume, fade, border and border_color.
Subtitles (captions[])
start, end and text. They're exported as SRT and WebVTT and, with burn_subtitles: true, burned into the picture.
Outputs
video.mp4 (H.264 + AAC), audio.wav (final soundtrack), song.wav (only with a main song), subtitles.srt, subtitles.vtt, qc.json (length, resolution, sound sources, warnings) and manifest.json.
Limits
- Files up to 250 MB, images up to 8192 × 8192 and media up to 610 s.
- Up to 150 shots, 20 audio tracks, 20 layers, 100 titles and 500 subtitles.
- Titles, layers and subtitles end inside the video. A transition can't be longer than half of either shot it joins.
- Disk paths, URLs and playlists aren't accepted as media.