Sume API로 영상의 길이, 해상도, fps 확인하기

Sume API로 영상의 길이, 해상도, 프레임 레이트를 확인하려면 Sume에 호스팅된 클립을 frames: false와 함께 POST /v1/video-inspect로 보내세요. 과금되지 않는 이 프로브는 duration_seconds, width, height, fps, has_audio와 나머지 컨테이너 정보를 반환하며, 기본 모드인 sync에서는 30초 안에 끝나면 결과를 담아 200으로 응답합니다.

요청 규칙은 영상 검사 문서에서, 프로브의 필드 목록은 Sume API 레퍼런스에서 가져왔으며, 둘 다 2026-09-26에 확인했습니다.

메타데이터만 요청하려면 어떻게 하나요?

video_url에는 여러분 워크스페이스에 있는 최대 1,800초 길이의 media.sume.com 아티팩트나 에셋을 넣고, frames: false와 함께 보내세요. frames: false는 스틸 없이 프로브만 한다는 뜻입니다. transcribe를 켜지 않으면 아무것도 과금되지 않습니다.

Idempotency-Key 헤더, 30초를 넘기는 프로브에 대한 202 응답, GET /v1/video-inspect/:id 폴링은 다른 검사와 똑같이 동작합니다. 자세한 내용은 영상 검사 개요에서 다룹니다.

curl -X POST https://api.sume.com/v1/video-inspect \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: probe-talk-001" \
  -d '{
    "video_url": "https://media.sume.com/artifacts/artf_demo/talk.mp4",
    "frames": false
  }'

프로브는 어떤 필드를 반환하나요?

API 레퍼런스는 probe를 워커가 프로브한 컨테이너 정보이며 읽기 전용이라고 설명합니다. has_audio, is_still, hdr 외의 모든 필드는 null일 수 있습니다.

다른 미디어 도구를 호출하기 전에 무엇을 확인해야 하나요?

다른 미디어 도구가 Job을 거부할 이유가 되는 질문 대부분은 프로브로 미리 답할 수 있습니다.

• has_audio: 오디오 트랙이 없는 클립에서 오디오 분리는 detach_source_has_no_audio로, 검사 전사는 inspect_source_has_no_audio로 실패합니다. 문서는 먼저 probe.has_audio를 확인하라고 안내합니다.
• duration_seconds: 영상 프레임의 모든 at 값은 길이보다 작아야 하며, 그렇지 않으면 Job이 frame_time_out_of_range로 실패합니다. 영상 필터와 영상 프레임은 최대 300초, 트림, 오디오 분리, 검사는 최대 1,800초 길이의 소스를 받습니다.
• fps: output.fps를 생략하면 Timeline 1.0은 소스의 레이트로 렌더링하며, 이와 다른 레이트는 프레임을 반복하거나 버립니다. 영상의 프레임 레이트나 해상도 바꾸기를 참고하세요.
• hdr: 영상 필터는 PQ와 HLG 소스를 hdr_source_unsupported로 거부하며, 프로브를 보면 프로그램을 제출하기 전에 이를 알 수 있습니다. 현재 exact 트림도 이런 소스를 거부하고 keyframe 정밀도를 쓰도록 안내합니다.

일부 클립에서는 왜 너비와 높이가 뒤바뀌어 보이나요?

width와 height는 영상 스트림에 저장된 크기이며, rotation은 적용되지 않고 그 옆에 따로 보고됩니다. 현재 검사가 만드는 스틸은 정방향으로 나옵니다. 스틸은 스케일하기 전에 회전되며, rotation이 직각 회전(90, −90, 270)이면 스틸의 width와 height가 서로 바뀝니다. 세로로 촬영한 클립의 정방향 크기가 필요하다면 프로브의 두 값도 같은 방식으로 바꾸세요.

전사문을 기준으로 자를 때는 어느 길이를 믿어야 하나요?

전사문도 요청하면(transcribe: true) 전사문은 자체 오디오 정보를 보고합니다. transcript.audio_duration_seconds는 전사문을 만든 16 kHz 모노 wav의 길이이며, API 레퍼런스에 따르면 디코더 프라이밍만큼 probe.duration_seconds보다 짧을 수 있습니다. 그러니 그 오디오를 기준으로 자를 때는 이 값을 믿으세요. 전사문의 audio_sample_rate와 audio_channels는 소스가 아니라 그 음성 인식용 사본을 설명하므로(현재 16000과 1), 소스의 값은 프로브에서 읽으세요.

모든 미디어 도구의 길이와 크기 상한을 한 페이지에서 보려면 영상 편집 API 한도를 참고하세요.