API ドキュメント
Llumi Cut は HTTP サービスです。素材をアップロードし、JSON のタイムラインを送信して、結果をダウンロードします。このページではフィールドの概要を説明します。検証済みの完全なスキーマは、各インストール環境の /openapi.json にあります。
認証
インストール環境ごとに専用のキーがあります。すべての /v1 ルートで送信してください：
Authorization: Bearer <あなたのキー>流れ
- アップロード：各ファイルを
POST /v1/assets?kind=image|video|audioで、ファイルをバイナリのボディとして送信します。{"id": "…"}が返ります。 - キュー登録：
POST /v1/rendersでタイムラインを JSON として送信し、編集をキューに入れます。Idempotency-Keyヘッダーを使えば、リトライしてもレンダリングが重複しません。 - ポーリング：
statusがcompletedになるまでGET /v1/renders/{id}を呼び出し、その後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 と一致する必要があります。
| フィールド | 値 |
|---|---|
duration | 3〜600 秒 |
width · aspect | 640、1280、1920（長辺） · 16:9、9:16、1:1 |
fps | 24 または 30 |
background | 余白の帯の色、#RRGGBB |
transition · transition_duration | cut、fade、fadeblack、fadewhite、dissolve、slideleft、slideright、wipeleft、wiperight、smoothleft、smoothright、circleopen、circleclose · 0.1〜2 秒 |
image_motion | none、zoom_in、zoom_out、pan_left、pan_right、auto |
fade_in · fade_out | 動画全体と音声のフェード、0〜5 秒 |
audio_asset_id · pauses | 任意のメイン楽曲と、最大 10 回のデジタル無音 |
カット（clips[]）
| フィールド | 値 |
|---|---|
asset_id · duration | 画像または動画 · 最大 60 秒 |
trim_start · speed | 素材内の開始秒数 · 0.25〜4 |
volume | クリップ自体の音量、0〜2（0 でミュート） |
fit | contain（帯あり）または cover（トリミングして全面表示） |
freeze · motion | 最初のフレームで静止 · Ken Burns の動き |
effects | 最大 6 つ：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（最大 5 行）、start、end、position（9 つの配置）または画面に対する比率で指定する 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。
制限
- ファイルは最大 250 MB、画像は最大 8192 × 8192、素材は最大 610 秒。
- カットは最大 150、音声トラック 20、レイヤー 20、テロップ 100、字幕 500。
- テロップ、レイヤー、字幕は動画の終了までに終わる必要があります。トランジションの長さは、つなぐどちらのカットの半分も超えられません。
- ディスクパス、URL、プレイリストは素材として受け付けません。