비디오 분석

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

비디오 분석은 공개 HTTPS 비디오 URL을 받아 Job 기반의 장면별 분해 결과를 반환합니다. 에이전트가 기존 클립을 읽어야 할 때(구조, 훅, B롤 삽입 지점) 사용하세요. 트렌드 발굴이나 바이럴 예측 도구가 아니며, 비디오를 생성하지도 않습니다 — 구조를 따라 만든 리믹스가 필요하면 생성 Format과 함께 사용하세요.

내부적으로는 비디오 이해 모델(TwelveLabs Pegasus)이 MP4를 보고 설명과 대사가 담긴 타입 있는 장면으로 나눈 뒤, ffmpeg가 장면마다 JPEG 스틸 한 장을 추출합니다(keyframe_url). 현재 analysis_version은 1.1입니다.

원격 MCP 래퍼는 video-analyses_create, video-analyses_get, video-analyses_list입니다. jobs_wait로 폴링하세요(일반적인 실행 시간은 3~5분이며 30~60초마다 폴링합니다).

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

분석 Job 만들기

필수: 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 URL422 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 스틸, 미러링에 실패하면 keyframe_mirror_failed:scene_N 경고와 함께 null), confidence(0~1)가 들어 있습니다.

스코프

스코프오퍼레이션
video_analyses:writePOST /v1/video-analyses
video_analyses:readGET /v1/video-analyses, GET /v1/video-analyses/:id

관련 문서