용어집
응답이나 API 레퍼런스의 필드 이름이 낯설 때 이 페이지를 참고하세요. 용어는 도메인별로 묶여 있습니다.
데이터 단위
| 용어 | 의미 |
|---|---|
| Video (영상) | 색인 생성의 입력 단위입니다. 미디어 파일 또는 URL 하나가 영상 하나이며 video_id로 식별합니다. |
| Scene (장면) | 자동 컷 전환 감지로 만들어지는, 영상 안의 타임코드 구간입니다. 하나의 클립으로 분석됩니다. 검색은 장면 단위로 결과를 반환합니다. |
| Job (작업) | 영상 하나에 대한 비동기 색인 생성 실행 한 번이며 job_id로 식별합니다. pending → running → done / failed로 전이합니다. 재색인하면 새 작업이 생깁니다. |
| Batch (배치) | 하나의 batch_id로 함께 제출한 URL 또는 파일 묶음입니다. 배치 엔드포인트는 제출 접수 기록이며 색인 생성 진행 상황이 아닙니다. |
| Burst (버스트) | 라이브 모니터링에서 SSAI 광고 브레이크 직전에 수집한 HLS 세그먼트 묶음입니다. 자체 요약과 라벨을 붙여 함께 분석합니다. |
| Namespace (네임스페이스) | 같은 코퍼스 안에서 데이터를 구분하는 태그입니다. 라이브 스트림에서 필터로 제공됩니다. |
scene_index | 영상 안에서 장면의 0부터 시작하는 순번입니다. |
start_ms / end_ms | 장면의 시작·끝 타임스탬프(밀리초)입니다. |
duration_ms | 영상 또는 광고 소재의 길이(밀리초)입니다. |
length_bucket | 필터로 쓰는 영상 길이 구분입니다. short(2분 이하), medium(30분 이하), long. |
external_content_id | MRSS 피드로 수집한 영상에 담긴 고객사 자체 콘텐츠 ID입니다. content_id=로 필터링합니다. |
| Cursor (커서) | 목록 엔드포인트의 불투명한 페이지네이션 토큰입니다. next_cursor를 cursor로 다시 전달하세요. null이면 마지막 페이지입니다. |
| NDJSON | 줄바꿈으로 구분한 JSON으로, 한 줄에 JSON 객체 하나입니다. 장면 스트림, 광고 매칭, 라이브 이벤트, 검색 AI 판정에서 사용합니다. |
검색
| 용어 | 의미 |
|---|---|
| Modality (모달리티) | 검색에 쓰는 임베딩 종류입니다. caption(서술형 설명), transcript(발화 그대로), omni(시각 + 오디오), both(caption + omni), all(세 가지 모두). |
k | 모달리티 열마다 반환하는 영상 수입니다. 기본값 20, 최대 100. |
scene_pool | 영상별로 묶기 전에 벡터 검색에서 가져오는 장면 후보 수입니다. 기본값 60, 최대 200. |
| Deep search (딥 검색) | POST /api/v1/search/deep: 같은 쿼리에 상위 후보를 대상으로 LLM 재순위화를 한 번 더 거칩니다. 순서가 더 정확해지는 대신 지연이 몇 초 늘어납니다. |
| Multimodal search (멀티모달 검색) | POST /api/v1/search/multimodal: 텍스트와 함께, 또는 텍스트 대신 이미지·오디오 URL로 검색합니다. |
| AI judge (AI 판정) | POST /api/v1/search(caption 모달리티)의 옵트인 옵션 judge: "text"입니다. 장면마다 0–10 관련도와 이유를 스트리밍하고, min_relevance(기본값 3) 이상인 장면만 남긴 summary를 보냅니다. |
score | 장면 매치의 유사도 점수입니다. 영상 점수는 가장 좋은 장면 점수와 매칭된 장면 수를 함께 반영합니다. |
브랜드 세이프티
| 용어 | 의미 |
|---|---|
| GARM | GARM Brand Safety Floor 카테고리로, World Federation of Advertisers가 발표한 브랜드 세이프티 프레임워크입니다. 색인 생성은 레벨이 있는 12개 슬러그 어휘를, 광고 검수는 11개 카테고리의 Brand Safety Floor를 사용합니다. 분류 체계와 판정을 참고하세요. |
| GARM level (GARM 레벨) | 영상 안에서 카테고리의 심각도입니다. low, medium, high. 장면 마커에는 none이 추가됩니다. |
garm_min_level | 검색과 영상 목록의 하한 필터입니다. 이 레벨 이상인 영상만 반환합니다. |
garm_categories | 장면 단위 GARM 플래그입니다(민감하게 잡으며 검토 전 상태). |
garm_video | 영상 단위 GARM 평가입니다. 확인된 카테고리마다 {category, level, reasoning} 항목이 하나씩 있습니다. |
block_decision | 광고 검수의 최종 판정입니다. allow 또는 block. |
| Rule (규칙) | 저장된 차단 목록이나 요청의 rules에 담긴 자연어 정책 한 줄입니다. 규칙마다 독립적으로 평가되며 blocklist.hits에 보고됩니다. |
| Matched rule ( 일치한 규칙) | blocklist.hits[i].matched가 true인 규칙입니다. |
| Fail-closed (실패 시 차단) | 검수 자체에서 오류가 나면 판정은 allow가 아니라 screening_failed: true와 함께 block입니다. |
| Explanation (설명) | 결정 근거를 인용하는 자유 형식 문장입니다. 표시용이며 파싱하지 마세요. |
광고 운영
| 용어 | 의미 |
|---|---|
| Ad (광고) | 등록된 광고 소재로, UUID ad_id로 식별합니다. 매칭, 검수에서 재사용합니다. |
| Ad status (광고 상태) | resolving(URL / VAST를 가져와 검증하는 중), ready(미디어 저장 완료, 사용 가능), failed(error에 사유). 파일 업로드는 즉시 ready입니다. |
source_type | 소재가 등록된 방식입니다. file, url, vast_url, vast_xml. VAST 입력은 미디어 URL까지 풀어서 처리합니다. |
| Ad analysis (광고 분석) | GET /api/v1/ads/{ad_id}/analysis: 소재가 판매하는 것(primary_brand, primary_product), 화면에 나오는 모든 것(brands, products), IAB / GARM 라벨을 반환합니다. |
| Ad matching (광고 매칭) | POST /api/v1/ads/match: 광고가 어울리는 장면을 NDJSON 이벤트로 스트리밍 합니다. analyzing, ad_analysis, agent_step, meta, 장면마다 result 하나, done(또는 error). |
brand_hints | 캡션 모델이 로고를 놓쳤을 때 매칭에 반영하는 선택 입력 브랜드 키워드입니다(대소문자 구분 없음). |
| Break point (삽입 지점) | 영상 안에서 광고를 넣을 수 있는 위치입니다. 광고 매칭 result 이벤트에서 timestamp_ms(절대 위치, 정수 밀리초)로 제공합니다. |
score | 매칭 result 이벤트에서 광고–장면 적합도를 0–10으로 나타내며, reason 문자열이 함께 옵니다. |
IAB 분류 체계
| 용어 | 의미 |
|---|---|
| IAB Content Taxonomy | IAB Tech Lab의 콘텐츠 카테고리 표준입니다. iab_t1 필터는 Tier-1 이름을 받고, 리프 라벨은 iab_content_leaf로 반환됩니다. |
iab_audience_interest_leaf | 영상에 어울리는 시청자의 IAB Audience Taxonomy 관심사 세그먼트입니다. |
iab_audience_purchase_intent_leaf | IAB Audience Taxonomy 구매 의도 세그먼트입니다(예: 자동차·여행 구매 의향자). |
iab_ad_product_leaf | 콘텐츠 옆에 어울리는 광고의 IAB Ad Product Taxonomy 카테고리입니다. |
| Leaf (리프) | 분류 체계 가지에서 가장 구체적인 라벨입니다. API는 리프 라벨을 반환하고 Tier-1 이름으로 필터링합니다. |
수명 주기
| 용어 | 의미 |
|---|---|
| Job status (작업 상태) | pending(대기) → running(파이프라인 실행 중) → done(성공) / failed(오류). |
total_scenes / done_scenes | 작업의 색인 생성 진행 상황입니다. 지금까지 분석한 장면 수와 전체 장면 수입니다. |
reason_code | 색인 생성 실패의 고정된 원인 코드입니다(예: source_forbidden, url_unreachable, media_unreadable). 영상이 failed일 때만 의미가 있습니다. |
| Indexed (색인 완료) | 작업이 done에 도달한 상태입니다. 요약, 라벨, 장면, 집계를 사용할 수 있고 영상이 검색됩니다. |
| Re-index (재색인) | 기존 영상에 대한 이후의 색인 생성 시도입니다. 새 job_id가 생기고, index_trigger는 reindex, reindex_run_id는 해당 실행을 식별합니다. |
indexed_at | 가장 최근에 끝난 시도의 종료 시각입니다. 성공 여부와 무관합니다. |
created | URL 제출에서 호출이 영상을 새로 만들었으면 true, 같은 URL이 이미 색인 생성 중이라 기존 ID를 반환했으면 false입니다. |
| Custom summary (맞춤 요약) | 색인된 영상을 instructions에 맞춰 작성한 요약으로, 표준 결과와 별도로 저장됩니다. 상태는 queued → ready / rejected / failed입니다. |
| MRSS feed (MRSS 피드) | 대시보드에 등록해 일정 주기로 폴링하는 미디어 RSS 피드입니다. 항목마다 external_content_id가 있는 영상이 됩니다. |
storage_path | 업로드와 광고 레코드에서 반환되는 내부 객체 키입니다. API 호출에는 필요하지 않습니다. |
| Quota (사용 한도) | 조직별 영상 수, 분, 광고 수 한도입니다. GET /api/v1/usage로 확인합니다. |
인증
| 용어 | 의미 |
|---|---|
| API key (API 키) | vuf_live_<keyid>.<secret> 형식이며 모든 요청에 Authorization: Bearer ...로 보냅니다. 인증을 참고하세요. |
| keyid | 키의 공개 식별자 부분으로, 서버에서 키를 조회할 때 씁니다. |
| secret | 키의 비공개 부분입니다. 생성 시 한 번만 표시되며 서버는 해시만 저장합니다. |
| Organization (조직) | 영상, 광고, 피드, 사용 한도를 소유하는 계정입니다. 모든 키는 하나의 조직에 속하고, 목록 엔드포인트는 그 조직 범위로 한정됩니다. |