2026-09-25미디어 도구

Timeline 1.0 API로 롱폼 영상을 조립하는 방법

Timeline 1.0은 오디오 스파인 하나와 순서가 있는 영상 슬롯 1–200개를 MP4 하나로 렌더링합니다. 모든 URL은 Sume에 호스팅되어야 하며, plan 사전 검사는 과금되지 않습니다.

읽는 시간 6분Sume

Sume Timeline 1.0은 선언적 문서로 롱폼 영상을 조립합니다. 이 문서는 오디오 스파인 하나와 순서가 있는 video[] 슬롯으로 이루어지며, POST /v1/timeline-1.0/render가 이를 MP4 하나로 렌더링합니다. ffmpeg 컴파일은 서버가 직접 하므로, 호출자가 필터그래프, 코덱, 셸 조각을 보낼 일은 없습니다.

아래 내용은 모두 2026-09-25에 확인한 Timeline 1.0 문서를 기준으로 합니다.

Timeline 1.0은 무엇을 하고, 무엇을 다른 도구에 맡기나요?

Timeline 1.0은 유일한 공개 조립 표면입니다. 여기서 조립이란 시퀀스, 트랜지션, 오디오 스파인을 말합니다. 그 밖의 작업은 문서가 별도 도구로 안내하며, 이 도구들은 트림, 필터, 오디오 분리와 타임라인 합성과 타임라인 오디오에서 다룹니다.

클립 하나의 [start, end) 구간: 영상 트림.
오디오 트랙을 내구성 있는 wav 또는 mp3로: 오디오 분리.
렌더 옵션이 아닌 dim, crop 등의 픽셀 패스: 영상 필터.
스틸과 영상을 한 화면에 동시에: 타임라인 합성. 그 MP4를 video[]에 넣으세요.
재사용할 병합 오디오 파일: 타임라인 오디오. 이 렌더 안에서만 필요한 잘린 보이스오버는 audio.parts[]에 둡니다.

타임라인은 어떻게 렌더링하나요?

audio.duration_seconds(1–1800), audio.url이나 audio.parts[] 중 하나(audio.mode가 "silence"가 아닌 경우), 그리고 video[] 슬롯 1–200개를 보내세요. 모든 URL은 이미 워크스페이스에 있는 media.sume.com 아티팩트나 에셋이어야 합니다. https://example.com/… 같은 호스트 밖 URL은 접수 단계에서 거부되므로 먼저 POST /v1/media-imports로 가져오세요. Idempotency-Key는 필수입니다.

기본 mode는 async입니다. mode: "sync"를 보내면 완료된 Job을 200으로 받기 위해 최대 30초 기다리고, 그렇지 않으면 202를 받아 폴링합니다. GET /v1/timeline-1.0/:id는 없으므로 GET /v1/jobs/:id/status와 GET /v1/jobs/:id/result를 폴링하세요. POST /v1/models/sume/timeline-1.0/runs도 같은 본문을 받습니다.

호스팅 MCP 서버에서는 timeline_create, jobs_wait, timeline_get 순서로 호출합니다. 쓰기에는 idempotency_key가 필요하고, OAuth에서는 mcp:write도 필요합니다. Claude Code, Cursor, Codex를 Sume에 연결하기를 참고하세요.

curl -X POST https://api.sume.com/v1/timeline-1.0/render \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: timeline-001" \
  -d '{
    "audio": {
      "url": "https://media.sume.com/artifacts/artf_demo/voice.wav",
      "duration_seconds": 24
    },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/intro.mp4", "start": 0, "duration": 8 },
      {
        "source_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
        "start": 8,
        "duration": 16,
        "transition": { "type": "fade", "duration": 0.25 }
      }
    ]
  }'

프로그램을 구성하는 필드는 무엇인가요?

선언한 start가 그대로 기준이 됩니다. 컴파일러가 xfade를 보정하며, 슬롯을 미리 앞당기지 않습니다.

Timeline 1.0 문서의 프로그램 필드, 2026-09-25 확인.
필드	규칙
`audio.duration_seconds`	출력 길이. 필수. 1–1800초.
`audio.url` / `audio.parts[]`	Sume에 호스팅된 스파인 하나, 또는 재 TTS 없이 샘플 도메인에서 이어 붙이는 갭 없는 조각 최대 20개. 둘은 함께 쓸 수 없음.
`audio.mode`	`"silence"`: 스파인 파일 없이 선언된 길이.
`audio.gain_db`	−60…12. silence와 함께 쓸 수 없음.
`video[].source_url`	Sume에 호스팅된 클립 또는 스틸. 스틸은 정지 화면으로 유지됨.
`video[].start`	`video[0].start`는 0이어야 함. 이후 start는 계속 커져야 함.
`video[].duration`	≥ 0.2초. 영상 커버리지가 스파인보다 최대 0.5초 짧아도 됨.
`video[].fit`	`cover`(기본값), `contain`, `stretch`, `blur` 중 하나.
`video[].transition`	첫 슬롯 이후에만 가능: `fade`, `wipeleft`, `wiperight`, `slideup`, `slidedown`, `dissolve` 중 하나. 1초 이하, 더 짧은 이웃 슬롯 길이의 50% 이하, 출력 프레임 최소 한 장.
`output.width` / `height`	256–2160 사이의 짝수 정수.
`output.fps`	`24`, `25`, `30`, `60` 중 하나. 생략하면 소스에 맞춤.
`output.fade_in_seconds` / `fade_out_seconds`	0–5초. 합계 ≤ 출력 길이.
`soundtrack`	선택 배경음: `url`, `gain_db`, `loop`, `fade_out_seconds` ≤ 10, `duck_db` 0–20(silence가 아닌 실제 스파인 필요).
`render.strategy`	`auto`(기본값, 세그먼트가 12개를 넘으면 청크로 나눔), `chunked`, `single`(슬롯 12개 초과 시 거부) 중 하나.

과금되기 전에 타임라인을 어떻게 확인하나요?

과금되지 않는 컴파일 사전 검사인 POST /v1/timeline-1.0/plan을 호출하세요. 스키마, Sume 호스트 URL 검사, 컴파일러를 실행한 뒤 duration_seconds, segment_count, billable_minutes, estimated_cost_usd_micros, filtergraph_summary가 담긴 object: timeline_plan을 반환합니다.

plan은 Job을 만들지 않고, 크레딧을 예약하지 않으며, 미디어를 내려받지도 않습니다. Idempotency-Key도 필요 없습니다. 짧은 소스의 패딩이나 루프 경고는 plan으로 예측할 수 없습니다.

무엇이 반환되고, 과금은 어떻게 되나요?

제출에 성공하면 type: timeline_render, model: sume/timeline-1.0인 Job이 반환됩니다. Job이 result_ready가 되면 GET /v1/jobs/:id/result는 video_url, duration_seconds, segment_count, billable_minutes, 선택적 warnings[]를 담은 kind: timeline_render를 반환합니다. 소프트 경고(패딩되거나 루프된 짧은 소스, 스냅된 트랜지션, 무시된 스틸 모션)는 실패가 아닙니다.

기본 출력은 1080×1920 MP4입니다. output.fps를 생략하면 소스가 이미 쓰고 있는 프레임레이트로 렌더링하고, 프레임레이트가 있는 소스가 하나도 없을 때만 30으로 렌더링합니다. 소스와 다른 프레임레이트를 쓰면 몇 프레임마다 한 프레임을 반복하거나 버리게 되며, 이는 output_fps_resamples_sources로 보고됩니다.

공개 요율은 ceil(output minute)당 청구되고, 예약되는 분량은 ceil(audio.duration_seconds / 60)분입니다. 프로바이더 추론 없이 워커의 ffmpeg만 실행됩니다. 요율은 API 요금에 있으며, 문서는 GET /v1/catalog에서 실시간으로 확인하라고 안내합니다.

타임라인이 왜 거부되었나요?

거부 응답에는 안정적인 코드가 붙습니다. 그중 일부는 다음과 같습니다.

timeline_must_start_at_zero: video[0].start가 0이 아닙니다.
transition_on_first_segment: video[0]에 트랜지션이 있습니다.
invalid_segment_timing / segment_overlap: start가 증가하지 않거나, 슬롯이 xfade 범위를 넘어 겹칩니다.
too_many_chained_transitions: 인접한 페이드가 8개를 넘습니다. 하드 컷을 넣으세요.
audio_parts_shorter_than_duration: 선언한 part 길이의 합이 duration_seconds보다 짧습니다.
render_strategy_unsafe: 슬롯이 12개를 넘는데 strategy: "single"을 지정했습니다.
unsupported_media_source / source_not_found: 호스트 밖 URL이거나 죽은 URL입니다.
model, filtergraph, ffmpeg_args, codec, crf 같은 프로바이더 키나 ffmpeg 키를 보내면 400입니다.

출처

Timeline 1.0

작성자 Sume