Sume 타임라인 합성·타임라인 오디오 API 사용법

타임라인 합성(POST /v1/timeline-1.0/compose)은 Sume에 호스팅된 스틸 하나와 영상 하나를 한 화면에 동시에 올려 MP4 샷 하나를 반환합니다. 타임라인 오디오(POST /v1/timeline-1.0/audio)는 Sume에 호스팅된 오디오를 이어 붙이거나 잘라 내구성 있는 media.sume.com 파일로 만듭니다. 둘 다 Timeline 1.0 렌더에 쓸 소재를 준비하며, 어느 쪽도 클립을 순서대로 잇지 않습니다.

아래 내용은 2026-09-25에 확인한 타임라인 합성과 타임라인 오디오 문서를 기준으로 합니다.

렌더 대신 합성이나 타임라인 오디오를 써야 할 때는 언제인가요?

• 합성은 샷 하나를 만듭니다. 이미지 다음에 영상을 잇는 것은 합성 모드가 아닙니다. 렌더에서 인접한 video[] 슬롯이 이미 그렇게 합니다.
• 타임라인 오디오는 재사용할 수 있는 파일을 만듭니다. 렌더 하나 안에서만 필요한 이어 붙이기는 그 렌더의 audio.parts[]에 두고, 이 Job은 건너뛰세요.
• 둘 다 이 워크스페이스의 media.sume.com에 이미 있는 URL만 받습니다. 호스트 밖 URL은 접수 단계에서 거부되므로 먼저 POST /v1/media-imports로 가져오세요(미디어 입력과 출력 참고).
• 둘 다 Idempotency-Key가 필요합니다. 기본 mode는 async이며, mode: "sync"는 완료된 Job을 200으로 받기 위해 최대 30초 기다리고, 그렇지 않으면 202를 받아 폴링합니다.

스틸과 영상을 한 화면에 넣으려면 어떻게 하나요?

operation(stack 또는 overlay), image.url, video.url을 보내세요. stack과 overlay를 고르는 필드는 mode가 아니라 operation이며, mode는 평소와 같은 async / sync / webhook 옵션입니다. 이미지는 프로브했을 때 스틸이어야 하고(compose_image_not_still), 영상은 영상이어야 합니다(compose_video_not_video).

출력 길이는 항상 영상 레이어에서 정해집니다. video.duration이 있으면 그 값을, 없으면 source_in부터 파일 끝까지를 씁니다. 스틸은 클립 전체 동안 유지되며 클립 길이를 늘릴 수 없습니다. 상한은 300초이고, 소스보다 긴 video.duration은 소스 길이로 제한되며 compose_duration_clamped_to_source 경고가 붙습니다.

기본 출력은 영상 레이어 고유의 프레임레이트로 만든 1080×1920 MP4입니다. output.width / output.height를 나중에 조립할 타임라인에 맞춰 두면 샷이 두 번 스케일되지 않습니다. 오디오는 영상의 오디오를 그대로 씁니다. 무음 영상은 compose_video_has_no_audio 경고만 내는데, 조립할 때 Timeline 1.0 스파인이 오디오를 공급하기 때문입니다.

curl -X POST https://api.sume.com/v1/timeline-1.0/compose \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: timeline-compose-001" \
  -d '{
    "operation": "stack",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/banner.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/talk.mp4" },
    "layout": { "split": "horizontal", "image_region": "top", "ratio": 0.5 },
    "output": { "width": 720, "height": 1280, "fps": 25 }
  }'

stack과 overlay에는 어떤 레이아웃 키를 쓰나요?

stack은 한 프레임을 두 영역으로 나눠 배치합니다. 기본값인 horizontal / top / 0.5는 반배너 형태로, 위에는 스틸, 아래에는 영상이 오며 영상이 나머지 영역을 정확히 차지합니다. stack 키와 overlay 키를 섞으면 400(compose_stack_takes_no_overlay_layout / compose_overlay_takes_no_stack_layout)입니다.

오디오 파일은 어떻게 이어 붙이거나 나누나요?

operation: "concat"은 parts[]를 받습니다. 순서가 있는 part 1–20개이며, 각각 { url, source_in?, duration? } 형태입니다. 이어 붙이기는 샘플 도메인에서 이뤄져 재 TTS도, 이음새의 무음도 없으며, part들은 같은 채널 레이아웃을 써야 합니다. 결과(kind: timeline_audio)에는 audio_url 하나, duration_seconds, segments[](index, start, duration_seconds)가 담깁니다. segments[]는 Timeline 1.0의 video[].start를 다시 맞출 때 기준으로 삼는 오프셋입니다.

operation: "split"은 최상위 url과 ranges[]를 받습니다. range는 1–20개이고 각각 { start, end? } 형태이며, end를 생략하면 파일 끝까지를 뜻합니다. range는 서로 겹쳐도 되고, 반환되는 segment마다 자체 audio_url이 있습니다. 토킹 헤드 MP4에서 여러 구간이 필요하면 오디오 분리를 한 번 실행한 뒤 split하세요.

output.format의 기본값은 wav(pcm_s16le, 샘플 단위로 정확)이고, mp3(더 작지만 모든 경계에 프라이밍 패딩이 다시 붙음)도 쓸 수 있습니다. 다시 이어 붙이거나 립싱크에 쓸 파일이라면 wav를 유지하세요. 생성되는 오디오는 최대 1800초입니다.

curl -X POST https://api.sume.com/v1/timeline-1.0/audio \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: timeline-audio-concat-001" \
  -d '{
    "operation": "concat",
    "parts": [
      { "url": "https://media.sume.com/artifacts/artf_demo/line1.wav" },
      { "url": "https://media.sume.com/artifacts/artf_demo/line2.wav", "source_in": 0.1, "duration": 1.8 }
    ]
  }'

결과는 어떻게 받고, 과금은 어떻게 되나요?

두 도구 모두 전용 GET 경로가 없습니다. GET /v1/jobs/:id/status와 GET /v1/jobs/:id/result를 폴링하세요. 합성 결과는 video_url(새 artf_)과 duration_seconds를 담은 kind: timeline_compose이며, 그 MP4를 Timeline 1.0의 video[]에 넣으면 됩니다. 호스팅 MCP 서버에서는 timeline_compose → jobs_wait → jobs_result, 그리고 timeline_audio → jobs_wait → jobs_result 순서로 호출합니다. 쓰기에는 idempotency_key가 필요하고, OAuth에서는 mcp:write도 필요합니다.

둘 다 Job당 정액으로 과금됩니다. 합성이 정액인 이유는 워커가 프로브하기 전까지 video.duration이 생략될 수 있기 때문입니다. 프로바이더 추론 없이 워커의 ffmpeg만 실행됩니다. 요율은 API 요금에 있으며, 문서는 GET /v1/catalog에서 실시간으로 확인하라고 안내합니다.

합성이나 오디오 Job이 왜 거부되었나요?

• compose_image_region_wrong_axis: 가로 분할에 left / right, 또는 세로 분할에 top / bottom을 지정했습니다.
• audio_concat_requires_parts, audio_concat_takes_no_url, audio_concat_takes_no_ranges: parts가 없거나 split 필드가 들어간 concat입니다.
• audio_split_requires_url, audio_split_requires_ranges, audio_split_takes_no_parts: url이나 ranges가 빠졌거나 parts가 들어간 split입니다.
• audio_range_end_before_start: end ≤ start인 range입니다.
• audio_parts_channel_mismatch: concat의 part들이 같은 채널 레이아웃이 아닙니다.
• unsupported_media_source / source_not_found: 호스트 밖 URL이거나 죽은 URL입니다.
• filtergraph, ffmpeg_args, codec, crf 같은 프로바이더 키나 ffmpeg 키를 보내면 400입니다.