Llumi Cut · Nordic Byte

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

  1. Upload each file with POST /v1/assets?kind=image|video|audio and the file as the binary body. It returns {"id": "…"}.
  2. Queue the edit with POST /v1/renders and the timeline as JSON. Use the Idempotency-Key header so a retry doesn't create a second render.
  3. Poll GET /v1/renders/{id} until status is completed, then download each file from result.files.

Endpoints

MethodPathWhat it does
GET/healthService status
POST/v1/assets?kind=image|video|audioUploads a binary file and returns its ID
POST/v1/rendersValidates the timeline and queues it
GET/v1/rendersLatest 100 renders
GET/v1/renders/{id}Status, progress, events and errors
POST/v1/renders/{id}/cancelCancels a queued or running render
POST/v1/renders/{id}/retryRetries 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=NDeletes stopped renders older than N days

Timeline

Only title, duration and clips are required. The shot durations must add up to duration.

FieldValues
duration3–600 s
width · aspect640, 1280 or 1920 (long side) · 16:9, 9:16, 1:1
fps24 or 30
backgroundColour of the letterbox bars, #RRGGBB
transition · transition_durationcut, fade, fadeblack, fadewhite, dissolve, slideleft, slideright, wipeleft, wiperight, smoothleft, smoothright, circleopen, circleclose · 0.1–2 s
image_motionnone, zoom_in, zoom_out, pan_left, pan_right, auto
fade_in · fade_outFade of the whole video and its sound, 0–5 s
audio_asset_id · pausesOptional main song and up to ten pauses of digital silence

Shots (clips[])

FieldValues
asset_id · durationImage or video · up to 60 s
trim_start · speedStart second in the source · 0.25–4
volumeThe clip's own sound, 0–2 (0 mutes it)
fitcontain (with bars) or cover (fills by cropping)
freeze · motionFreezes the first frame · Ken Burns movement
effectsUp 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_durationTransition 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