Sume API로 가로 영상을 세로 9:16으로 변환하기

Sume API로 가로 영상을 세로로 바꾸려면 POST /v1/video-filter로 16:9 클립에서 9:16 영역을 잘라 내거나, 기본 출력이 1080×1920인 POST /v1/timeline-1.0/render의 슬롯에 클립을 넣고 fit 모드를 고르세요. 두 방법 모두 이미 media.sume.com에 호스팅된 클립을 읽어 새 MP4를 반환합니다.

아래 내용은 2026-09-26에 확인한 영상 필터, Timeline 1.0, 타임라인 합성 문서와 Sume API 레퍼런스를 기준으로 합니다. 문서가 아니라 Sume의 Timeline 컴파일러에서 확인한 동작은 컴파일러가 현재 동작하는 방식대로 설명합니다.

어떤 클립을 변환할 수 있나요?

이 도구들은 여러분 워크스페이스에 있는 media.sume.com 아티팩트나 에셋만 읽습니다. 이전 Sume Job이 반환한 MP4가 그 예입니다. 공개 인터넷에서 가져오는 기능은 없으며, https://example.com/… 같은 호스트 밖 URL은 접수 단계에서 unsupported_media_source로 거부됩니다. 모든 생성 요청에는 Idempotency-Key가 필요합니다.

클립이 Sume 아바타 영상이라면 변환이 필요 없을 수도 있습니다. Avatar Video의 aspect_ratio는 9:16을 받으며, 이 값이 기본값입니다. 기존 영상을 변환하는 대신 세로 영상을 새로 생성하려면 세로 9:16 영상 생성을 참고하세요.

16:9 영상을 9:16으로 크롭하려면 어떻게 하나요?

영상 필터의 crop op를 쓰세요. 이 op는 사각형을 소스 프레임에 대한 비율로 받고 x + width ≤ 1이어야 하며, 컴파일러는 yuv420p에 맞게 이를 짝수 픽셀로 내림합니다. 이 op의 나머지 범위는 트림, 필터, 오디오 분리에 정리되어 있습니다.

높이를 꽉 채운 9:16 영역의 너비는 16:9 프레임 너비의 81/256, 약 0.3164이고, 이 영역을 가운데에 두면 x는 약 0.3418입니다. 이 숫자들은 문서의 규칙이 아니라 저희가 직접 계산한 값입니다. 피사체가 가운데에서 벗어나 있다면 x를 0에서 약 0.6836 사이로 옮겨 따라가세요. 출력은 잘라 낸 영역 자체의 크기이므로(같은 방식으로 계산하면 1920×1080 소스에서 약 606×1080), 아래 요청은 허용 목록에 있는 scale 필터를 더해 1080×1920으로 만듭니다.

curl -X POST https://api.sume.com/v1/video-filter \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: vertical-crop-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/landscape.mp4",
    "ops": [{ "op": "crop", "x": 0.3418, "y": 0, "width": 0.3164, "height": 1 }],
    "filtergraph": "scale=1080:1920"
  }'

어떤 Timeline fit 모드를 써야 하나요?

Timeline 1.0은 기본적으로 1080×1920 MP4를 렌더링하며, output.width / output.height로 256에서 2160 사이의 다른 짝수 크기를 지정할 수 있습니다. 각 video[] 슬롯의 fit은 16:9 클립을 그 세로 프레임에 어떻게 맞출지 정합니다.

Timeline으로 세로 버전을 렌더링하려면 어떻게 하나요?

출력 전체를 덮는 슬롯 하나를 보내고 fit을 지정하세요. 현재 렌더의 소리는 video[]의 클립이 아니라 오디오 스파인과 선택 사항인 soundtrack 배경음에서 나옵니다. 그래서 말소리가 있는 클립이라면 먼저 POST /v1/audio-detach로 오디오 트랙을 분리하세요. 그 기본 출력인 wav가 바로 audio.url이 원하는 형태입니다. audio.duration_seconds(1–1800)는 클립 길이로 설정하세요.

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: vertical-blur-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/landscape.mp4",
        "start": 0,
        "duration": 24,
        "fit": "blur"
      }
    ]
  }'

대신 가로 클립 위쪽에 배너를 둘 수 있나요?

네, 타임라인 합성으로 할 수 있습니다. operation: "stack"으로 POST /v1/timeline-1.0/compose를 호출하면 스틸 하나와 영상 하나를 한 프레임 안에 나눠 배치합니다. 기본 레이아웃(horizontal, top, 0.5)은 스틸을 위에, 영상을 아래에 두며, 기본 출력은 1080×1920입니다. video_fit은 cover, contain, stretch 중 하나를 받으며, blur는 합성의 fit 값이 아닙니다. 영상 레이어의 오디오는 그대로 전달됩니다. 레이아웃 키는 타임라인 합성과 타임라인 오디오에서 다룹니다.

경로별 한도는 어떻게 되나요?

클립 길이와 소리를 어디에서 가져올지에 따라 고르세요. 세 경로 모두 전용 GET이 없으므로 GET /v1/jobs/:id/status와 GET /v1/jobs/:id/result를 폴링해 새 video_url을 받으세요.

• 300초보다 긴 소스는 필터에서 output_duration_exceeded로 실패합니다. Timeline fit을 쓰거나, 영상 트림으로 클립을 300초 이하 조각으로 나누세요.
• POST /v1/video-filter/check는 Job을 만들지 않고 예약도 하지 않은 채 crop 프로그램을 무료로 검증합니다. 이 검사는 필터 허용 목록 글에서 다룹니다.
• API 요금 요율표에는 Timeline 렌더가 출력 분당 $0.10로 나와 있고, 렌더는 ceil(audio.duration_seconds / 60)분을 예약합니다. 필터와 합성은 Job당 과금되며, 실시간 요율은 GET /v1/catalog에 나와 있습니다.