영상의 특정 시간에 이미지 넣는 방법

영상의 특정 시간에 이미지를 넣으려면, 두 타임스탬프 사이에서만 이미지를 원래 화면 위에 띄우거나(오버레이) 원래 화면 대신 보여 주고(컷어웨이), 나머지 부분은 그대로 두세요. Sume에서는 클립과 이미지가 이미 Sume에 호스팅되어 있다면, 타임라인 합성으로 클립의 그 구간에만 이미지를 합성한 뒤, 클립에서 분리한 오디오 위에서 Timeline 1.0 렌더 한 번으로 조각들을 다시 순서대로 이어 붙이면 됩니다.

아래 내용은 2026-09-27에 확인한 Sume의 타임라인 합성, Timeline 1.0, 오디오 분리 문서와 Sume API 레퍼런스의 필드 설명을 기준으로 합니다. 현재 동작이라고 설명한 내용은 Sume의 코드에서 확인한 것입니다.

이미지를 몇 초 동안만 오버레이하려면 어떻게 하나요?

20초 길이의 1920×1080 클립에서 5초부터 9초까지 이미지를 띄운다고 해 보겠습니다. 두 파일 모두 앞서 실행한 Sume Job의 출력처럼 이미 워크스페이스에 있는 media.sume.com 아티팩트나 에셋이어야 합니다. Sume에는 컴퓨터에 있는 파일을 올리는 공개 업로드 경로가 없습니다. 에셋 업로드 경로는 공개 API 레퍼런스에서 숨겨져 있습니다(엔드포인트별로 받는 URL). 호출은 세 번 필요합니다.

• 클립에 POST /v1/audio-detach를 호출하면 소리가 wav로 반환됩니다. 현재 컴파일러에서 렌더의 소리는 스파인과 선택 사항인 사운드트랙에서만 나오므로, 이렇게 해야 클립의 오디오가 유지됩니다.
• operation: "overlay", 이미지, 그리고 video.source_in: 5와 video.duration: 4를 지정한 클립으로 POST /v1/timeline-1.0/compose를 호출하면, 그 구간 위에 이미지를 얹은 4초짜리 MP4가 반환됩니다. 기본값이 1080×1920이므로 output을 클립 크기에 맞추세요.
• POST /v1/timeline-1.0/render는 wav 위에 슬롯 세 개를 놓습니다. 5초까지의 클립, 합성한 샷, 그리고 source_in: 9부터 다시 이어지는 클립입니다.

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: overlay-5s-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/badge.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "source_in": 5, "duration": 4 },
    "layout": { "position": "bottom", "width_ratio": 0.4 },
    "output": { "width": 1920, "height": 1080 }
  }'

조각들은 어떻게 다시 이어 붙이나요?

GET /v1/jobs/:id/result에서 합성한 샷의 video_url을 읽은 뒤 렌더링하세요. 슬롯들이 분리한 wav 위에 빈틈없이 이어지므로 소리는 끊기지 않고 재생됩니다. 또 문서는 각 슬롯에 선언된 start를 기준으로 삼기 때문에, 이미지는 5초에 나타납니다.

• 여기서는 transition 없이 하드 컷을 쓰세요. 그래야 세 조각이 클립을 나눈 지점에서 맞물립니다.
• 과금되지 않는 POST /v1/timeline-1.0/plan은 비용을 내기 전에 렌더 본문을 검사합니다.

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: overlay-5s-render-001" \
  -d '{
    "audio": { "url": "https://media.sume.com/artifacts/artf_demo/clip.wav", "duration_seconds": 20 },
    "output": { "width": 1920, "height": 1080 },
    "video": [
      { "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "start": 0, "duration": 5 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/overlay-5s.mp4", "start": 5, "duration": 4 },
      { "source_url": "https://media.sume.com/artifacts/artf_demo/clip.mp4", "start": 9, "duration": 11, "source_in": 9 }
    ]
  }'

이미지는 화면의 어디에 놓이나요?

오버레이는 스틸을 자체 화면 비율을 유지하는 플레이트로 만들어, 프레임을 가득 채운 영상 위에 띄웁니다. 플레이트는 항상 가로 중앙에 놓이므로 모서리 위치는 없습니다. layout.position은 플레이트를 top(기본값), center, bottom 중 한 곳에 고정하고, layout.width_ratio는 플레이트 너비를 프레임 대비 비율로 정합니다(기본값 0.9). 이미지와 영상이 프레임을 나눠 쓰게 하려면 대신 operation: "stack"을 쓰세요. 둘을 한 프레임의 서로 다른 영역에 나눠 배치합니다. 최대 300초 길이의 클립 전체에 이미지를 올린다면 합성 호출 한 번으로 충분합니다. 이 경우와 모든 오버레이 키는 영상에 로고나 워터마크 넣기에서 다룹니다.

원래 화면 대신 이미지를 넣으려면 어떻게 하나요?

합성은 건너뛰고 스틸에 별도 슬롯을 주세요. 스틸은 정지 화면으로 유지되므로, start: 5에 duration: 4인 스틸 슬롯은 소리가 계속 재생되는 동안 5초부터 9초까지를 이미지로 바꾸고, 클립은 앞의 예처럼 source_in: 9에서 다시 이어집니다. 현재 코드에서 기본 fit인 cover는 프레임과 모양이 다른 이미지를 잘라 내고, contain은 이미지를 프레임 안에 맞게 스케일한 뒤 남는 곳을 검은색으로 채웁니다. 토킹 헤드 영상에 B-roll 넣기도 컷어웨이에 같은 패턴을 씁니다.

비용은 얼마이고, 한도는 어떻게 되나요?

각 단계는 따로 과금되며, 기본적으로 5.5% 에이전트 수수료가 더해집니다. 오디오 분리와 합성은 Job당 과금되고, 요율은 GET /v1/catalog에 있습니다. 렌더는 API 요금에 나온 출력 분당 $0.10 기준으로 ceil(audio.duration_seconds / 60)분을 예약하고, 예약한 금액보다 더 청구하지 않습니다. 따라서 20초 예제는 일 분을 예약합니다.

• 합성한 구간은 최대 300초입니다. 길이는 항상 영상 레이어에서 정해지며, 스틸로는 길이를 늘릴 수 없습니다.
• 이미지는 프로브했을 때 스틸이어야 하고(compose_image_not_still), 클립은 영상이어야 합니다(compose_video_not_video).
• 렌더 한 번은 슬롯 1–200개로 1초에서 1,800초까지 출력하므로, 렌더 하나에 시간을 지정한 이미지를 여러 장 넣을 수 있습니다.
• 오디오 분리 한 번은 최대 900초 분량의 오디오를 만들므로, 더 긴 클립은 range 두 개로 분리하고 두 파일을 모두 audio.parts[]로 넘기세요.