비디오 분석

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

현재 SoT. 이 표면으로 새 작업을 시작하지 마세요.

dest와 prod 기본: 비디오 검사 — POST /v1/video-inspect(MCP video_inspect)로 프로브 + 스틸 + 선택적 전사. 프로브와 스틸은 무료입니다. 기본 mode: sync.

Dest (api.dev.sume.com): SUME_COM_VIDEO_ANALYSIS_ENABLED=false. POST /v1/video-analyses는 410 video_analysis_retired. MCP video-analyses_*는 tools_list에서 빠집니다. 저장된 vana_ 행은 GET으로 읽습니다. dest에서 의미 질문/구간은 tools_list에 보일 때만 video_analyze / video_segment(신뢰 origin api.dev.sume.com + TwelveLabs 키 — 프로덕션 불가).

Prod (api.sume.com): #5953 PR-C2까지 생성을 받습니다. dest의 410은 프로덕션 장애가 아닙니다.

이 페이지는 레거시 video_analysis / vana_ 리소스(타입 있는 scenes[])를 설명합니다. 트렌드 발굴이나 바이럴 예측이 아니며, 비디오를 생성하지도 않습니다. 클립 구조로 Format을 만드는 일은 리믹스 작업입니다.

생성이 켜진 환경에서는 비디오 이해 모델(TwelveLabs Pegasus)이 MP4를 장면으로 나누고, ffmpeg가 장면의 매 초마다 JPEG 스틸을 추출합니다(keyframes). 장면 대표 스틸은 keyframe_url입니다. 현재 analysis_version은 1.1입니다.

원격 MCP 래퍼 video-analyses_create / _get / _list도 같은 플래그를 따릅니다. 프로덕션은 PR-C2까지 목록에 있고 dest에서는 빠집니다. 남은 Job은 jobs_wait로 폴링하세요(일반적인 실행 시간은 3~5분, 30~60초마다).

정확도 주의: 긴 비디오일수록 정확도가 떨어집니다. 짧은 클립이 가장 믿을 만한 결과를 줍니다.

분석 Job 만들기 (프로덕션, PR-C2까지)

dest 호출자는 POST하지 마세요. 비디오 검사를 쓰고, 목록에 있을 때만 dest 전용 video_analyze / video_segment를 쓰세요.

필수: video_url. 선택: max_scenes(2~40, 기본 24), include_transcript(true이면 각 장면의 audio에 해당 장면의 대사 speech가 담기고, 아니면 audio는 null입니다), 그리고 평소의 mode / webhook_url / wait_timeout_seconds 통신 필드입니다.

제출에 성공하면 202와 함께 vana_… 리소스 id, video_analysis Job(request_id), 그리고 status_url / result_url이 돌아옵니다.

미디어 임포트(POST /v1/media-imports)로 만든 내구성 있는 media.sume.com URL이나 완료된 Sume 생성 산출물을 사용하세요. Higgsfield 방식의 media_id 반입 게이트는 없습니다.

가격 참고

접수된 분석마다 현재 고정 추정 기준으로 Sume 사용량 0.30 USD가 예약되고 확정됩니다. 실제 가격은 GET /v1/catalog와 OpenAPI에서 확인하세요.

길이 제한

상한	동작
소프트(약 90초)	Job은 성공합니다. 응답에 `low_confidence_long_video` 경고가 포함될 수 있습니다.
하드(300초)	프로브 이후 안정적인 길이 오류로 거부됩니다.

지원하지 않는 입력

입력	결과
YouTube URL	`422 unsupported_source`
HTTPS가 아니거나 사설·localhost	접수 단계에서 거부됩니다
비디오가 아닌 에셋	에이전트가 읽을 수 있는 안정적인 코드로 실패합니다

폴링하고 읽기

준비되면 리소스에는 비디오 전체 메타데이터와 타입이 정해진 scenes[] 배열이 담깁니다. 각 장면에는 연속된 start_seconds / end_seconds, duration_seconds, summary, visual, 선택적인 shot_type / camera_motion, on_screen_text, audio(include_transcript를 요청했으면 { speech, has_speech, has_music }, 아니면 null), keyframe_url(장면 대표 JPEG 스틸 — 장면 길이의 40%에 가장 가까운 1초 샘플, 1초 미만 장면은 기존 40% 지점. 미러링에 실패하면 keyframe_mirror_failed:scene_N 경고와 함께 null), keyframes(그 장면의 매 정수 초를 덮는 { t, url } 배열. 한 초가 실패해도 장면 전체가 빠지지 않으며 해당 행은 url: null과 keyframe_mirror_failed:scene_N:t_T 경고), confidence(0~1)가 들어 있습니다. 300초 하드 길이 제한이 스틸 수 상한(~300장)이기도 합니다. 별도의 1초 텍스트/컨텍스트 트랙은 없습니다.

스코프

스코프	오퍼레이션
`video_analyses:write`	`POST /v1/video-analyses`
`video_analyses:read`	`GET /v1/video-analyses`, `GET /v1/video-analyses/:id`