우리는 MP4 파일에서 프레임을 샘플링하고, 이를 시각 능력을 갖춘 LLM (Large Language Model)에 입력하여 이벤트, 객체 및 동작을 설명하는 구조화된 JSON 보고서를 생성하는 명령줄 비디오 분석기를 구축할 것입니다. 이러한 종류의 도구는 콘텐츠 모더레이션 (Content Moderation), 자동 장면 로깅 (Automated Scene Logging), 또는 원본 영상을 검색 가능한 문서로 변환하는 데 유용합니다. Oxlo.ai는 입력 길이에 관계없이 요청당 고정 요금을 부과하기 때문에, 한 번에 수십 개의 프레임을 보내는 것이 단일 텍스트 프롬프트를 보내는 것과 동일한 비용이 들며, 이는 긴 컨텍스트 시각 워크로드 (Long-context vision workloads)를 토큰 기반 과금 방식보다 훨씬 더 예측 가능하게 만듭니다.

필요한 사항

• Python 3.10 이상
• pip install openai opencv-python
• https://portal.oxlo.ai에서 발급받은 Oxlo.ai API 키
• 작업 디렉토리에 있는 sample.mp4라는 이름의 샘플 비디오 파일

1단계: 비디오에서 프레임 추출하기

저는 OpenCV를 사용하여 비디오를 읽고 몇 초마다 하나의 프레임을 샘플링합니다. 페이로드 (Payload)를 관리 가능한 수준으로 유지하기 위해, API로 전송하기 전에 각 프레임의 크기를 조정하고 JPEG로 인코딩하여 base64로 변환합니다.

import cv2
import base64

...

2단계: 시스템 프롬프트 작성하기

시스템 프롬프트 (System Prompt)는 에이전트의 지침 세트입니다. 저는 모델이 매번 예측 가능하고 파싱 가능한 (Parseable) 출력을 반환할 수 있도록 이를 엄격한 계약으로 취급합니다.

SYSTEM_PROMPT = """You are a video analysis engine. You receive a sequence of JPEG frames sampled from a single video.
Your job is to return a structured JSON report with exactly these top-level keys:
- summary: one sentence describing the overall video
...

3단계: 멀티모달 메시지 구축하기

OpenAI SDK는 멀티모달 (Multimodal) 입력을 위해 콘텐츠 블록 배열을 허용합니다. 짧은 텍스트 지침을 앞에 추가한 다음, 페이로드 크기를 줄이기 위해 각 base64 프레임을 낮은 상세도 (Low detail)의 데이터 URL로 추가합니다.

def build_message(frames):
    content = [{"type": "text", "text": f"Analyze these {len(frames)} frames from the video and return the structured report."}]
    for b64 in frames:
...

4단계: Oxlo.ai 호출하기

이제 전체 배치를 Oxlo.ai로 전송합니다. 저는 kimi-k2.6을 사용하는데, 이 모델은 비전 (vision)을 처리할 수 있고 131K 컨텍스트 윈도우 (context window)를 제공하여 단일 요청으로 긴 프레임 시퀀스를 쉽게 커버할 수 있기 때문입니다. Oxlo.ai는 요청당 고정 가격제 (flat per-request pricing)를 사용하므로, 자세한 내역은 pricing page에서 확인할 수 있습니다.

from openai import OpenAI
import json

...

5단계: CLI로 패키징하기

경로를 수정하지 않고도 여러 영상 폴더에서 재사용할 수 있도록, 인자 파싱 (argument parsing) 기능을 포함하여 파이프라인을 단일 스크립트로 패키징합니다.

import argparse
import cv2
import base64
...

실행하기

스크립트를 video_analyzer.py로 저장하고, 동일한 디렉토리에 샘플 영상을 배치한 뒤 다음 명령어를 실행하세요.

python video_analyzer.py sample.mp4 --interval 5 --max-frames 10

출력 예시:

{
  "summary": "한 사람이 사무실 공간을 걸어가다가 화이트보드 앞에 멈춰 서서 메모를 작성하고 있으며, 근처 책상에는 노트북이 열려 있습니다.",
  "objects": [
...

다음 단계

이 프로젝트를 발전시킬 수 있는 두 가지 방향이 있습니다. 첫째, 임베딩 (embedding) 단계를 추가하는 것입니다. 생성된 JSON 요약을 bge-large 또는 e5-large를 사용하여 Oxlo.ai의 임베딩 엔드포인트 (embeddings endpoint)로 전달한 다음, 벡터 (vectors)를 데이터베이스에 저장하여 의미론적 의미 (semantic meaning)를 기반으로 비디오 라이브러리 전체를 검색할 수 있게 만드세요. 둘째, 배치 프로세서 (batch processor)를 구축하는 것입니다. 무료 티어 (Free tier)에서 제공하는 일일 60회 요청 또는 유료 플랜을 사용하여 밤새 영상 디렉토리를 재귀적으로 분석하고, 파일당 하나의 JSON 보고서를 작성하도록 만드세요.