영상에 로고나 워터마크를 넣는 방법

영상에 로고나 워터마크를 넣으려면 로고 이미지를 모든 프레임 위에 정해진 크기와 위치로 올린 뒤 클립을 다시 인코딩하세요. Sume에서는 두 파일 모두 이전 Sume 출력물처럼 이미 Sume에 호스팅되어 있어야 합니다. 로고 스틸과 영상을 operation: "overlay"와 함께 POST /v1/timeline-1.0/compose로 보내세요. Sume는 로고의 너비를 프레임 너비의 width_ratio 비율로 맞추되 모양은 유지하고, 위·가운데·아래 중 한 곳에 고정해 클립 전체 동안 띄운 뒤, 클립의 소리가 담긴 새 MP4 하나를 반환합니다.

세부 내용은 2026-09-27에 확인한 타임라인 합성 문서와 Sume API 레퍼런스의 합성 스키마에서 가져왔습니다. 움직이는 로고나 엔드 카드는 다른 작업이며, 로고 애니메이션에서 다룹니다.

영상에 로고를 오버레이하려면 어떻게 하나요?

모두 필수인 operation, image.url, video.url을 Idempotency-Key 헤더와 함께 보내세요. 호스트 밖 URL은 거부되므로 두 URL 모두 워크스페이스의 media.sume.com 파일이어야 합니다. 이미지는 스틸이어야 하고(아니면 compose_image_not_still), 영상은 영상이어야 합니다. 엔드포인트마다 어떤 URL을 받는지는 Sume API 미디어 URL 규칙에서 다룹니다.

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: logo-overlay-001" \
  -d '{
    "operation": "overlay",
    "image": { "url": "https://media.sume.com/artifacts/artf_demo/logo.png" },
    "video": { "url": "https://media.sume.com/artifacts/artf_demo/clip.mp4" },
    "layout": { "position": "top", "width_ratio": 0.2, "margin_ratio": 0.04 },
    "output": { "width": 1080, "height": 1920 }
  }'

로고의 크기와 위치는 어떻게 정하나요?

overlay에는 layout 키 네 개가 적용됩니다. width_ratio의 기본값 0.9는 프레임 대부분을 차지하므로, 로고라면 더 낮게 설정하세요.

• overlay에 stack 키(split, image_region, ratio, image_fit)를 보내면 400(compose_overlay_takes_no_stack_layout)입니다.
• output.width와 output.height(각각 256–2160)를 클립 고유의 크기에 맞추세요. 기본 출력은 영상의 프레임 레이트로 만든 1080×1920이므로, 기본값을 그대로 두면 가로 클립이 세로로 다시 프레이밍됩니다. 크기는 영상 검사의 무료 프로브로 알 수 있습니다.

영상의 길이와 소리는 어떻게 되나요?

길이는 항상 영상에서 정해집니다. video.duration이 있으면 그 값을, 없으면 video.source_in부터 파일 끝까지를 씁니다. 로고는 클립 전체 동안 유지되며 클립 길이를 늘릴 수 없고, 상한은 300초입니다. 클립의 오디오는 그대로 통과하며, 무음 영상은 compose_video_has_no_audio 경고만 냅니다.

합성 전용 GET 경로는 없습니다. GET /v1/jobs/:id/status를 폴링한 다음 GET /v1/jobs/:id/result를 호출하면, 새 video_url과 duration_seconds가 담긴 kind: timeline_compose가 돌아옵니다. 합성은 타임라인 합성 페이지에 나온 Job당 정액으로 과금되며, 문서는 GET /v1/catalog에서 실시간으로 확인하라고 안내합니다.

합성 overlay로 할 수 없는 것은 무엇인가요?

• 모서리 배치: 로고는 항상 가로 가운데에 놓이므로 위 가운데, 정가운데, 아래 가운데 중 한 곳에 자리합니다.
• 불투명도나 움직임: 위의 레이아웃 키가 overlay 설정의 전부이며, 스틸은 클립 전체 동안 그대로 유지됩니다.
• 투명도는 문서화되어 있지 않습니다. PNG의 투명한 영역이 투명하게 유지되는지 문서에 나와 있지 않으므로, 대량으로 처리하기 전에 테스트 렌더링을 한 번 확인하세요.
• 마크 두 개를 동시에 넣기: Job 하나는 스틸 하나만 받습니다. 두 번째 마크를 넣으려면 첫 Job의 video_url에 합성을 한 번 더 실행하세요.
• 영상 필터로 대신할 수도 없습니다. 영상 필터는 클립 하나만 읽으며, movie처럼 파일을 읽는 필터는 허용 목록에 없습니다.