미디어 도구

ffmpeg 필터 API: Sume 영상 필터 허용 목록과 검사

POST /v1/video-filter로 Sume에 호스팅된 클립에 허용 목록의 ffmpeg 필터를 적용합니다. 허용된 이름, filtergraph 규칙, 무료 검사, 인코딩 설정을 정리했습니다.

읽는 시간 6분Sume
전체 글

Sume의 ffmpeg 필터 API는 POST /v1/video-filter입니다. Sume에 호스팅된 클립 하나와 필터만 담은 filtergraph 문자열을 보내면, 서버가 모든 필터 이름을 허용 목록과 대조하고 그래프를 자체 입력과 출력으로 감싼 뒤 새 MP4로 인코딩합니다. argv, 코덱, 파일 경로는 보내지 않으며, POST /v1/video-filter/check는 같은 본문을 무료로 검증합니다.

아래 내용은 2026-09-26에 확인한 영상 필터 문서와 Sume API 레퍼런스를 기준으로 합니다. 문서는 허용 목록이 있는 곳으로 Sume의 필터 컴파일러를 지목합니다. 이 글의 필터 이름과 인코더 설정은 그 컴파일러에서 읽은 것으로, 현재 동작하는 방식을 설명합니다.

어떤 ffmpeg 필터를 쓸 수 있나요?

허용 목록에는 다섯 그룹에 걸쳐 66개의 이름이 있습니다. 모두 인라인 옵션만 받고 파일, 폰트, 모델, 명령, 소켓 옵션은 없으므로, 목록에 있는 어떤 필터도 경로를 읽거나 네트워크에 접근할 수 없습니다.

trim과 setpts(구간 컷은 영상 트림으로 하세요), drawtext, subtitles, movie, lut3d, 그리고 파일이나 소켓을 읽는 모든 필터는 목록에 없습니다. 알 수 없는 이름은 invalid_filtergraph(unknown_filter)로 실패하며, 메시지에 해당 토큰과 허용 목록이 표시됩니다.

영상 필터 문서와 Sume 필터 컴파일러의 허용 목록 기준, 2026-09-26 확인.
그룹허용 필터
톤과 색eq, lutyuv, lutrgb, lut, hue, colorbalance, colorchannelmixer, colorlevels, colortemperature, colorcontrast, colorcorrect, colorize, colorhold, colorkey, chromakey, chromahold, negate, monochrome, exposure, normalize, histeq, vibrance, swapuv, shuffleplanes, despill, vignette
블러, 샤프닝, 노이즈unsharp, boxblur, gblur, avgblur, smartblur, median, noise, deband, deflicker, dilation, erosion, sobel, edgedetect, cas
기하crop, scale, pad, hflip, vflip, transpose, rotate, setsar, setdar, zoompan, lenscorrection, perspective
시간fps, tpad, fade, framerate, tblend, tmix
합성(내부 라벨만)split, overlay, hstack, vstack, blend, drawbox, drawgrid, format

유효한 filtergraph는 어떤 모습인가요?

여기서 filtergraph는 필터로만 이루어집니다. 서버가 video_url의 입력을 [0:v]로 공급하고 마지막 필터를 인코더에 연결하므로, 그래프는 다음 규칙을 따릅니다.

  • 라벨이 아니라 필터로 시작하고 필터로 끝나야 합니다. split[a][b] 같은 내부 라벨은 괜찮지만, [0:v] 같은 스트림 지정자는 거부됩니다.
  • 최대 2,048자, 이름 있는 필터 최대 32개입니다. 그래프는 ops[](dim 또는 crop op 최대 8개)가 있으면 그 뒤에 실행됩니다.
  • 필터 안에는 공백을 넣을 수 없습니다. 옵션은 name=key=value:key=value 형태로 쓰세요.
  • ://, 백슬래시, 백틱, $, 큰따옴표, &, 탭, 줄바꿈은 쓸 수 없습니다.
  • 본문에 ffmpeg argv 필드를 넣을 수 없습니다. vf, filter, ffmpeg, cmd, codec, crf, -i 같은 키는 400 ffmpeg_fields_rejected를 반환합니다.

비용을 내기 전에 filtergraph를 어떻게 검사하나요?

같은 본문을 POST /v1/video-filter/check로 보내거나, 호스팅 MCP 서버에서 check_only: true로 video_filter를 호출하세요. 검사는 Job을 만들거나 크레딧을 예약하지 않고 인코딩과 같은 스키마, 허용 목록, 소스 검사를 실행합니다. 나머지 계약은 트림, 필터, 오디오 분리에서 다룹니다. 응답에는 다음 필드가 있습니다.

  • object: video_filter_check, valid, 그리고 encode: "not_run".
  • diagnostics[]: 항목마다 severity(error), code, message가 있고, 선택적으로 field, next_action, details가 붙습니다.
  • program: 정규화된 video_url, ops, filtergraph, filter_count, filters(컴파일된 이름만, argv 없음)입니다. 본문 자체가 거부되었으면 null입니다.
  • 유효할 때의 estimate(currency, usd_micros, usd_cents, label), 그리고 next_action: submit_video_filter 또는 fix_program_and_recheck.
curl -X POST https://api.sume.com/v1/video-filter/check \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "filtergraph": "eq=contrast=1.2:saturation=0.8,gblur=sigma=2"
  }'

Sume는 필터를 적용한 영상을 어떻게 인코딩하나요?

검사를 통과한 본문을 Idempotency-Key와 함께 POST /v1/video-filter로 제출한 뒤, 다른 미디어 도구와 마찬가지로 Job 봉투를 폴링하세요. 결과(kind: video_filter)에는 새 video_url과 컴파일된 filters[]가 담기며, 프로그램이 바꾸지 않는 한 출력은 소스의 기하 정보, 프레임 레이트, 오디오를 그대로 유지합니다.

인코더는 설정할 수 없습니다. 현재는 다음 설정으로 실행됩니다.

  • 영상: libx264, 프리셋 veryfast, CRF 20, yuv420p. 소스의 프레임 레이트를 알 수 있으면, 그 레이트를 기준으로 키프레임이 매초 한 번 들어가도록 간격을 설정합니다.
  • 오디오: filtergraph 밖에서 192 kbps AAC로 재인코딩되며, filtergraph는 영상 스트림만 봅니다. 오디오 트랙이 없는 소스도 받지만 filter_source_has_no_audio 경고가 붙습니다.
  • 컨테이너: +faststart를 적용한 MP4.
  • HDR 소스(PQ 또는 HLG)는 hdr_source_unsupported로, YUV 계열이 아닌 픽셀 포맷은 unsupported_pixel_format으로 거부됩니다.

한도와 비용은 어떻게 되나요?

인코딩은 GET /v1/catalog에 나온 요율로 Job당 과금되며, 검사는 무료입니다. 프로바이더 추론은 없고 워커의 ffmpeg만 실행됩니다.

출처

관련 글

작성자 Sume