영상 전환 효과(트랜지션) API: 크로스페이드·와이프·슬라이드

Sume API로 클립 사이에 전환 효과(트랜지션)를 넣으려면 Timeline 1.0 렌더(POST /v1/timeline-1.0/render)에서 첫 번째 이후의 원하는 video[] 슬롯에 transition: { type, duration }을 지정하세요. type은 fade, wipeleft, wiperight, slideup, slidedown, dissolve 중 하나이며, 트랜지션은 그 슬롯으로 들어가는 경계를 나타냅니다.

아래 내용은 2026-09-26에 확인한 Timeline 1.0 문서와 Sume API 레퍼런스의 필드 설명을 기준으로 합니다. 현재 동작이라고 설명한 내용은 Sume의 코드에서 확인한 것입니다. 렌더 문서의 나머지 부분은 롱폼 영상을 조립하는 방법에서 다룹니다.

경계마다 무슨 일이 일어나나요?

각 클립은 이미 워크스페이스에 있는 media.sume.com 아티팩트나 에셋이어야 합니다. 앞서 실행한 Sume Job의 출력이 그 예입니다. 트랜지션의 duration은 요청 스키마에서 1초로 제한되며, 경계에서 그 밖에 일어날 수 있는 일은 아래 표에 정리했습니다.

두 클립 사이에 크로스페이드를 어떻게 넣나요?

선언한 시작 시점이 그대로 기준이 되므로, 페이드가 들어갈 자리를 만들려고 슬롯을 옮기지 마세요. 현재 컴파일러에서 슬롯으로 들어가는 크로스페이드는 그 슬롯의 start 직전에 트랜지션 길이만큼 진행되며(xfade 오프셋은 start에서 트랜지션의 duration을 뺀 값), 들어오는 클립은 자신의 source_in부터 슬롯의 duration에 트랜지션 길이를 더한 만큼을 공급합니다.

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-transitions-001" \
  -d '{
    "audio": { "url": "https://media.sume.com/artifacts/artf_demo/voice.wav", "duration_seconds": 18 },
    "output": { "fps": 30 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/a.mp4", "start": 0, "duration": 6 },
      {
        "source_url": "https://media.sume.com/artifacts/artf_demo/b.mp4", "start": 6, "duration": 6,
        "transition": { "type": "fade", "duration": 0.5 }
      },
      {
        "source_url": "https://media.sume.com/artifacts/artf_demo/c.mp4", "start": 12, "duration": 6,
        "transition": { "type": "wipeleft", "duration": 0.4 }
      }
    ]
  }'

트랜지션 길이가 왜 요청한 값과 다른가요?

트랜지션은 정수 개의 프레임으로 렌더링됩니다. 현재 컴파일러는 프레임 그리드에서 벗어난 길이를 가장 가까운 정수 프레임으로 스냅하며, 이때 길이는 최대 반 프레임까지 바뀝니다. 결과에는 요청한 초와 적용된 초를 담은 transition_snapped_to_frame 경고가 붙고, 타임라인상의 위치는 바뀌지 않습니다. 예를 들어 25 fps에서 0.30초는 7.5프레임이므로 8프레임(0.32초)으로 렌더링됩니다. 반올림하면 프레임이 하나도 남지 않는 길이는 조용히 하드 컷으로 바뀌는 대신 transition_not_frame_aligned로 거부됩니다.

그리드는 출력 프레임 레이트에 따라 달라집니다. output.fps를 생략하면 렌더는 소스가 쓰는 프레임 레이트를 고르므로, 제출 시점의 프레임 검사는 생략된 값이 될 수 있는 가장 느린 레이트인 24 fps를 기준으로 합니다. 정확한 길이가 중요하다면 output.fps(24, 25, 30, 60 중 하나)를 지정하고, 위 예시가 30 fps에서 그렇게 하듯 정수 프레임에 맞는 길이를 고르세요.

트랜지션이 왜 하드 컷이 되었나요?

현재 컴파일러에서는 들어오는 클립에 source_in 이후로 슬롯의 duration과 트랜지션 길이를 합친 만큼의 분량이 없으면, 렌더가 그 경계를 하드 컷으로 처리하고 transition_downgraded_to_cut 경고를 냅니다. 타임라인상의 위치는 바뀌지 않고 Job도 그대로 완료됩니다. 트랜지션을 유지하려면 source_in을 낮추거나, 슬롯을 줄이거나, 더 긴 클립을 쓰세요.

이 경우는 렌더만 알 수 있습니다. 과금되지 않는 plan 사전 검사는 미디어를 내려받지 않으므로, 짧은 소스 때문에 하드 컷으로 바뀌는 경고를 예측할 수 없습니다.

트랜지션은 몇 개까지 연달아 넣을 수 있나요?

종류와 상관없이 연속으로 최대 8개입니다. 문서는 이를 인접한 페이드라고 부릅니다. 연속된 아홉 번째 트랜지션은 too_many_chained_transitions로 거부되며, 해결 방법은 하드 컷, 즉 transition이 없는 슬롯 하나를 넣는 것입니다. 코드는 두 가지 이유를 듭니다. 연달아 이어진 크로스페이드의 오프셋이 누적되고, 이 상한이 있어야 모든 타임라인에 청크 렌더가 분할할 수 있는 하드 컷이 보장됩니다. 기본 render.strategy인 auto는 세그먼트가 12개를 넘으면 청크로 나눕니다.

검은 화면에서 페이드인하거나 검은 화면으로 페이드아웃하려면 어떻게 하나요?

슬롯 트랜지션이 아니라 각각 0–5초인 output.fade_in_seconds와 output.fade_out_seconds를 쓰세요. API 레퍼런스에 따르면 두 필드는 화면을 검은색에서 밝히거나 검은색으로 어둡게 하고, 소리도 무음에서 키우거나 무음으로 줄이며, 정수 프레임에 맞춰 스냅됩니다. 두 값을 합친 길이가 출력 안에 들어가야 하며, 그렇지 않으면 요청이 edge_fades_exceed_output으로 거부됩니다.

API 요금에 나온 렌더의 공개 요율은 출력 분당 $0.10이며, 예약되는 분량은 ceil(audio.duration_seconds / 60)분입니다.