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, 재생 목록은 미디어로 받지 않습니다.