Llumi Cut · Nordic Byte

API 文档

Llumi Cut 是一个 HTTP 服务。上传素材，提交 JSON 时间线，然后下载结果。本页概述各字段；完整且经过校验的 schema 位于每个部署实例的 /openapi.json。

认证

每个部署实例有独立的密钥。在每个 /v1 路由的请求中发送：

Authorization: Bearer <你的密钥>

流程

  1. 上传：使用 POST /v1/assets?kind=image|video|audio 上传每个文件，请求体为文件二进制内容。返回 {"id": "…"}。
  2. 入队：使用 POST /v1/renders 提交剪辑任务，请求体为 JSON 时间线。使用 Idempotency-Key 请求头，避免重试时产生第二个渲染任务。
  3. 轮询：调用 GET /v1/renders/{id}，直到 status 变为 completed，然后从 result.files 下载每个文件。

接口

方法路径说明
GET/health服务状态
POST/v1/assets?kind=image|video|audio上传二进制文件并返回其 ID
POST/v1/renders校验时间线并加入队列
GET/v1/renders最近 100 个渲染任务
GET/v1/renders/{id}状态、进度、事件和错误
POST/v1/renders/{id}/cancel取消排队中或运行中的渲染任务
POST/v1/renders/{id}/retry重试已停止的渲染任务
DELETE/v1/renders/{id}删除已停止的渲染任务及其文件
GET/v1/renders/{id}/files/{name}下载一个输出文件
POST/v1/maintenance/purge?older_than_days=N删除超过 N 天的已停止渲染任务

时间线

只有 title、duration 和 clips 是必填项。各镜头时长之和必须等于 duration。

字段取值
duration3–600 秒
width · aspect640、1280 或 1920（长边） · 16:9、9:16、1:1
fps24 或 30
background黑边颜色，#RRGGBB
transition · transition_durationcut、fade、fadeblack、fadewhite、dissolve、slideleft、slideright、wipeleft、wiperight、smoothleft、smoothright、circleopen、circleclose · 0.1–2 秒
image_motionnone、zoom_in、zoom_out、pan_left、pan_right、auto
fade_in · fade_out整个视频及其声音的淡入淡出，0–5 秒
audio_asset_id · pauses可选主歌曲，以及最多十段数字静音停顿

镜头（clips[]）

字段取值
asset_id · duration图片或视频 · 最长 60 秒
trim_start · speed素材中的起始秒数 · 0.25–4
volume片段原声音量，0–2（0 为静音）
fitcontain（保留黑边）或 cover（裁切铺满）
freeze · motion定格第一帧 · Ken Burns 运动
effects最多六个：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与上一个镜头之间的转场

声音（audio_tracks[]）

asset_id、start、trim_start、duration、volume（0–2）、fade_in、fade_out、loop 和 duck。设置了 duck: true 的音轨，在歌曲、人声或片段原声播放时降低约 10 dB。

标题（texts[]）

text（最多五行）、start、end、position（九个位置）或以画面比例表示的 x/y、size、color、outline_color、outline、box、box_color、box_opacity、font、bold、italic 和 animation（none、fade、slide_up、slide_left、pop、typewriter）。

图层（overlays[]）

asset_id（图片或视频）、start、end、position 或 x/y、width、height（两者同时设置时铺满区域，用于分屏和宫格）、margin、opacity、trim_start、volume、fade、border 和 border_color。

字幕（captions[]）

start、end 和 text。导出为 SRT 和 WebVTT；设置 burn_subtitles: true 时烧录进画面。

输出

video.mp4（H.264 + AAC）、audio.wav（最终音轨）、song.wav（仅在有主歌曲时）、subtitles.srt、subtitles.vtt、qc.json（时长、分辨率、声源、警告）和 manifest.json。

限制