Sume API 출력 파일 형식: MP4·PNG·WebP·WAV·MP3
Sume API 엔드포인트별로 반환하는 파일입니다. Timeline과 편집 도구는 MP4, 이미지는 PNG·JPEG·WebP, 오디오는 WAV나 MP3, 전사문은 JSON입니다.
완료된 Sume Job은 파일을 media.sume.com의 산출물로 반환합니다. Timeline, 합성, 트림, 필터, 아바타 영상은 MP4이고, 자막을 입힌 영상도 현재 코드 기준으로 MP4입니다. 이미지 엔드포인트는 PNG, JPEG, WebP를 반환하며(모델의 카탈로그가 허용하면 SVG도), 오디오 분리와 타임라인 오디오는 WAV나 MP3를, 음성 인식은 단어별 타이밍이 담긴 JSON을 반환합니다. 문서에 컨테이너가 나와 있지 않으면 산출물의 content_type을 확인하세요.
형식과 기본값은 2026-09-27에 확인한 각 도구의 문서 페이지와 OpenAPI 레퍼런스에서 가져왔습니다. 인코더 설정은 Sume 미디어 컴파일러 코드에서 읽은 것으로, 현재 동작을 설명합니다. 산출물의 일반적인 형태는 영상 API 미디어 입출력에서 다룹니다.
엔드포인트마다 어떤 영상 형식을 반환하나요?
현재 코드에서 Timeline, 합성, 필터는 H.264 인코더인 libx264로 yuv420p와 AAC 오디오를 써서 인코딩합니다. 트림 문서도 exact 트림에 같은 인코더와 픽셀 형식을 명시합니다. 생성 클립, 립싱크, 업스케일은 문서에 해상도 옵션은 나와 있지만 컨테이너는 나와 있지 않습니다.
| 엔드포인트 | 출력 | 크기, 프레임 레이트, 코덱 |
|---|---|---|
| Timeline 렌더 | MP4 | 기본값 1080×1920. output.fps를 지정하지 않으면 프레임 레이트는 소스를 따름. 현재 코드: CRF 20, AAC 192 kbps |
| 타임라인 합성 | MP4 | 기본값 1080×1920, 영상 레이어의 프레임 레이트. 오디오는 영상에서 그대로 통과 |
| 영상 트림 | MP4 | exact(기본값)는 프레임 단위로 정확하게 재인코딩하며, 유지한 오디오는 AAC로 변환. keyframe은 스트림 카피 |
| 영상 필터 | MP4 | 프로그램이 바꾸지 않는 한 소스의 기하 정보, 프레임 레이트, 오디오를 유지. 현재 코드: CRF 20, AAC 192 kbps |
| 자막 | MP4(현재 코드) | 자막을 입힌 video_url, 문서에는 컨테이너 명시 없음 |
| 말하는 아바타 영상 | MP4 | 720p, aspect_ratio는 기본값 9:16 또는 1:1, 3:4, 4:3, 16:9 |
| 립싱크 | 영상 | VEED Fabric 1.0: 480p 또는 720p(기본값 720p). MiniMax H3 Max Lip Sync: 480p, 768p, 1080p(기본값 768p) |
영상 생성: POST /v1/videos | 영상 | 모델 목록에서 골라 요청한 resolution과 aspect_ratio. API 키를 붙여 GET /v1/videos/{id}/content에서 다운로드 |
| 영상 업스케일 | 영상 | 입력을 scale_ratio배로 확대(1.1–4, 기본값 2) |
어떤 이미지 형식을 받을 수 있나요?
POST /v1/images는 output_format을 받지만, 모델은 자기 카탈로그 항목에 나열된 값만 받으므로 먼저 GET /v1/images/models를 확인하세요. 각 결과에는 media_type이 들어 있고, 결과의 data[].url은 Sume에 호스팅된 서명 URL입니다.
| 엔드포인트 | 형식 | 크기 |
|---|---|---|
| Image API | png, jpeg, webp, svg 중 하나 | resolution과 aspect_ratio로 결정 |
| 이미지 업스케일 | png(기본값), jpg, webp | 입력 × upscale_factor(1–4, 기본값 2) |
| 배경 제거 | 알파 채널이 있는 PNG | — |
| 영상 프레임 | jpeg(기본값) 또는 png | 소스 크기. max_edge(16–2160)를 주면 긴 변을 제한 |
| 영상 검사 스틸 | jpeg(기본값) 또는 png | max_edge 64–2160, 기본값 768 |
오디오 엔드포인트는 어떤 오디오 형식을 반환하나요?
파일을 다시 이어 붙이거나 립싱크에 쓸 예정이라면 WAV를 유지하세요. 타임라인 오디오의 MP3 옵션은 경계마다 프라이밍 패딩을 다시 붙입니다.
| 엔드포인트 | 형식 | 옵션 |
|---|---|---|
| 오디오 분리 | wav(기본값, pcm_s16le) 또는 128 kbps mp3 | sample_rate는 16000, 44100, 48000 중 하나 또는 소스 값, channels는 source 또는 mono |
| 타임라인 오디오 | wav(기본값, pcm_s16le) 또는 mp3 | 생성되는 오디오 최대 1800초 |
| 텍스트 음성 변환 | 기본값 mp3(44,100 Hz, 128 kbps), wav 또는 raw | sample_rate는 8000, 16000, 22050, 24000, 44100, 48000 중 하나. wav와 raw는 encoding으로 pcm_f32le, pcm_s16le, pcm_mulaw, pcm_alaw 중 하나를 받음 |
| Music Router | type이 audio인 산출물 | 문서에 컨테이너 명시 없음 |
전사문은 어떤 형식인가요?
단어별 타이밍이 담긴 JSON입니다. 음성 인식은 text와 words[]를 반환하며, words[]의 각 항목은 오디오 시작부터 초 단위로 잰 { word, start, end }입니다. transcribe: true를 넣은 영상 검사는 text, words[], 선택적인 문장 단위 segments[], audio_url을 담은 transcript를 추가로 반환합니다.
돌려받은 파일의 형식은 어떻게 확인하나요?
URL로 짐작하지 말고 메타데이터를 읽으세요. Job 산출물에는 media.sume.com URL과 함께 image/png 같은 content_type이 있고, POST /v1/images 결과에는 media_type이 있습니다. 내보낼 때 클립의 크기나 프레임 레이트를 맞추려면 트림의 output 필드나 Timeline의 output 객체를 쓰세요. 프레임 레이트나 해상도 바꾸기에서 방법을 보여 줍니다.
출처
관련 글
개발자 카테고리의 다른 글
- Sume API 페이지네이션: cursor·starting_after·한도
Sume 목록 엔드포인트별 페이지 넘김 방식입니다. Format과 실행 목록은 cursor와 has_more, /v1/jobs는 starting_after를 쓰고, limit만 받는 목록에는 커서가 없습니다.
- Sume API 상태 값 정리: Job, 실행, 큐, 웹훅
Sume API 상태 값을 한곳에 모았습니다. Job, /v1/videos, Format·Agent 실행, 대량 실행 큐, 웹훅 전달, 사용량 행, 공유 권한, 잔액까지 다룹니다.
- Sume Job 타입과 동시성: 슬롯을 차지하는 호출
Sume 엔드포인트별 Job 타입과 슬롯 사용 여부입니다. 트림과 Timeline을 포함한 모든 생성 Job은 동시성 슬롯을 차지하고, 프레임과 검사는 차지하지 않습니다.
- Sume API 미디어 URL 규칙: 엔드포인트별 허용 URL
Sume 생성 엔드포인트는 공개 HTTPS 미디어 URL을 가져옵니다. 트림, 필터, 프레임, 검사, Timeline은 워크스페이스에 있는 media.sume.com URL만 받습니다.
작성자 Sume