Sume API로 영상의 프레임 레이트나 해상도 바꾸기

Sume API로 영상의 프레임 레이트나 해상도를 바꾸려면 Sume에 호스팅된 클립을 POST /v1/video-trim과 { width, height, fps } 형태의 output으로 재인코딩하거나, 허용 목록에 있는 scale과 fps 필터를 POST /v1/video-filter로 실행하세요. Timeline 1.0과 타임라인 합성도 출력 크기와 레이트를 받으며, 렌더는 레이트를 생략하면 소스를 보고 프레임 레이트를 정합니다.

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

크기나 프레임 레이트는 어떤 도구로 바꾸나요?

네 도구 모두 여러분 워크스페이스에 있는 media.sume.com 아티팩트나 에셋만 읽습니다. 클립의 현재 크기와 레이트를 먼저 보려면 무료 검사 프로브를 실행하세요. 영상의 길이, 해상도, fps 확인하기를 참고하세요.

영상 트림으로 클립의 크기나 프레임 레이트를 바꾸려면 어떻게 하나요?

트림의 output 컨폼은 기본값인 precision: "exact"에서만 동작하며, keyframe과 함께 쓰면 video_trim_output_requires_exact로 거부됩니다. 생략하면 클립은 소스의 크기와 레이트를 유지합니다. 현재 width나 height 중 하나만 지정하면 화면 비율이 유지되고, 둘 다 지정하면 클립이 정확히 그 크기로 스케일되며, 크기는 짝수 픽셀로 내림됩니다. 클립 전체를 컨폼하려면 start: 0부터 전체 길이(최대 900초)까지 자르세요. 트림의 나머지 내용은 트림, 필터, 오디오 분리에서 다룹니다.

curl -X POST https://api.sume.com/v1/video-trim \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: conform-720p30-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "start": 0,
    "end": 42,
    "output": { "height": 720, "fps": 30 }
  }'

영상 필터로 프레임 레이트를 바꿀 수 있나요?

네. scale, fps, framerate가 filtergraph 허용 목록에 있으므로 "filtergraph": "scale=1280:720,fps=30" 같은 프로그램으로 둘 다 바꿀 수 있습니다. 이 필터들이 없으면 필터 출력은 소스의 기하 정보와 프레임 레이트를 유지합니다. 소스는 최대 300초입니다. 먼저 POST /v1/video-filter/check로 프로그램을 무료로 검증하세요. 허용되는 이름은 모두 필터 허용 목록 글에 나와 있습니다.

Timeline은 출력 프레임 레이트를 어떻게 고르나요?

output.fps는 24, 25, 30, 60 중 하나를 받습니다. 생략하면 렌더는 소스가 이미 쓰고 있는 레이트를 사용합니다. 현재는 다음과 같이 동작합니다.

• 각 클립의 프로브된 레이트는 네 값 중 가장 가까운 값으로 맞춰지고, 그 레이트로 재생되는 영상의 총 길이(초)가 가장 긴 레이트가 선택됩니다. 동률이면 더 높은 레이트가 선택됩니다. 스틸에는 레이트가 없으며, 30은 레이트가 있는 소스가 하나도 없을 때만 적용됩니다.
• 출력과의 차이가 0.05 fps 이내인 소스는 일치하는 것으로 보고 경고를 내지 않습니다. 29.97 fps 영상은 30으로, 23.976 fps 영상은 24로 렌더링됩니다.
• 그 밖의 불일치는 몇 프레임마다 한 프레임을 반복하거나 버리며, 이는 움직임에서 떨림(judder)으로 나타납니다. 24 fps 영상을 30으로 렌더링하면 다섯 프레임 중 한 프레임이, 25 fps 영상은 여섯 프레임 중 한 프레임이 반복됩니다. 결과에는 소스가 원한 레이트와 함께 output_fps_resamples_sources 경고가 붙습니다.

클립이 두 번 스케일되지 않게 하려면 어떻게 하나요?

조립할 크기에 맞춰 한 번만 컨폼하세요. API 레퍼런스는 트림의 output을 조립할 타임라인에 맞추라고 하고, 합성 문서도 합성의 output.width와 output.height에 대해 같은 말을 합니다. 합성은 기본적으로 영상 레이어 고유의 프레임 레이트를 쓰는데, 프레임을 반복하거나 버리지 않는 레이트는 이것뿐입니다. 이와 다른 output.fps를 명시하면 output_fps_resamples_sources 경고가 발생합니다.

비용은 얼마인가요?

트림, 필터, 합성은 Job당 과금되고 실시간 요율은 GET /v1/catalog에 나와 있으며, 필터 검사와 영상 검사 프로브는 무료입니다. API 요금 요율표에는 Timeline 렌더가 출력 분당 $0.10로 나와 있고, 렌더는 ceil(audio.duration_seconds / 60)분을 예약합니다. 이 도구들은 모두 프로바이더 추론을 실행하지 않고 워커의 ffmpeg만 실행합니다.