분류 체계와 판정

API의 라벨은 세 곳에서 나옵니다. IAB Tech Lab 분류 체계(콘텐츠, 오디언스, 광고 상품), GARM 브랜드 세이프티 카테고리, 그리고 Pyler가 정의한 몇 가지 고정 어휘(장르, 음악 무드, 날씨, 사람 행동)입니다. 브랜드 세이프티 판정은 이와 별개로, GARM 탐지 결과와 정책 규칙으로 결정론적으로 계산합니다.

라벨 세트	표시 위치	단위
IAB Content	iab_content_leaf; 검색·영상 목록의 iab_t1 필터	영상
IAB Audience(관심사, 구매 의도)	iab_audience_interest_leaf, iab_audience_purchase_intent_leaf	영상
IAB Ad Product	iab_ad_product_leaf	영상
GARM	garm_categories(장면), garm_level(장면 마커), garm_video(영상), garm(광고 검수)	장면과 영상
장르	genre	영상
음악 무드, 날씨, 사람 행동	music_mood, weather, human_activity	장면

라벨 문자열은 파이프라인에서 정확한 enum으로 강제됩니다. 대소문자, 공백, 문장 부호까지 그대로 비교하세요.

IAB Content Taxonomy

IAB Tech Lab Content Taxonomy는 콘텐츠를 설명하는 "공통 언어"입니다. 주로 콘텍스츄얼 타기팅과 브랜드 세이프티에 쓰입니다. 파이프라인은 이 분류 체계의 Tier-1 / Tier-2 계층을 기준으로 동작하며 리프 라벨을 반환합니다.

영상에 라벨이 붙는 방식. IAB 카테고리는 장면마다 예측하지 않습니다. 요약 모델이 모든 장면 캡션, 대사, 개체를 함께 읽고, 영상이 무엇에 관한 것인지 설명하는 iab_content_leaf 라벨을 최대 5개 붙입니다. 따라서 장면 객체에는 IAB 필드가 없습니다. 상위 영상을 확인하세요.

필터링. POST /api/v1/search와 GET /api/v1/videos의 iab_t1은 Tier-1 콘텐츠 카테고리 이름(예: Food & Drink)을 받아 해당 가지에 속한 영상으로 결과를 좁힙니다.

IAB Audience Taxonomy

Audience Taxonomy는 업계에 오디언스 세그먼트의 공통 명명 체계를 제공합니다. Tier-1은 Demographic, Interest(특정 주제나 활동에 대한 사용자 관심사 기반 세그먼트), Purchase Intent(특정 상품·서비스의 구매 의도 기반 세그먼트)로 나뉩니다.

API는 콘텐츠에서 추론할 수 있는 두 가지를 추론하고, 콘텐츠만으로는 추론할 수 없는 Demographic은 제외합니다.

필드	해석
iab_audience_interest_leaf	이 영상에 어울리는 시청자의 관심사입니다.
iab_audience_purchase_intent_leaf	그 시청자가 구매를 고려할 가능성이 높은 상품·서비스 카테고리입니다.

IAB Ad Product Taxonomy

Ad Product Taxonomy는 광고하는 상품이나 서비스를 설명하는 방식을 표준화합니다. 퍼블리셔는 이를 통해 자동화 채널로 노출되는 광고 종류를 통제할 수 있습니다.

API는 이를 반대 방향으로 씁니다. iab_ad_product_leaf는 이 콘텐츠 옆에 어울리는 광고 상품 카테고리를 나열합니다(요리 영상이라면 식당이나 음식 배달 카테고리가 나올 수 있습니다). 광고 매칭이 이 라벨을 사용합니다. GET /api/v1/ads/{ad_id}/analysis는 등록된 광고 소재에 대해 같은 IAB·GARM 필드를 반환합니다.

GARM 브랜드 세이프티 카테고리

GARM Brand Safety Floor는 World Federation of Advertisers의 Global Alliance for Responsible Media 이니셔티브가 발표한 프레임워크로, 업계가 광고를 유해 콘텐츠와 분리하는 데 쓰는 카테고리를 정의합니다. API는 Pyler가 구현한 방식으로 이 프레임워크를 적용합니다. 서로 밀접한 두 가지 어휘를 사용합니다.

색인 생성과 검색(12개 카테고리, 3단계 레벨)

장면 garm_categories, 장면 마커 garm_level, 영상 garm_video, garm_min_level 필터에서 사용합니다.

슬러그
adult
weapons
crime
death_conflict
piracy
hate
profanity
substances
spam_harmful
terrorism
sensitive_social
misinformation

심각도 레벨은 high, medium, low입니다. 장면 마커에는 플래그가 없는 장면을 뜻하는 none이 추가됩니다.

장면 플래그와 영상 평가의 차이. 장면 단위 garm_categories는 클립 하나에 실제로 묘사된 것을 모두 기록하며 의도적으로 민감하게 잡습니다. 동화, 패러디, 스포츠 하이라이트, 각본 드라마에서 과잉 탐지가 납니다. 이후 요약 모델이 플래그된 카테고리를 영상 전체와 대조해 실제로 존재하는 것만 남깁니다. 따라서 garm_video에는 확인된 항목만 다음 형태로 들어 있습니다.

{ "category": "substances", "level": "medium",
  "reasoning": "Bar scene with repeated on-screen drinking.", "time_ranges": [] }

필터링. 검색과 영상 목록의 garm_min_level(low | medium | high)은 하한값입니다. "이 레벨 이상인 결과만"을 뜻합니다.

광고 검수(11개 카테고리)

POST /api/v1/ad-blocking과 POST /api/v1.1/ad-blocking은 광고 소재를 GARM Brand Safety Floor 기준으로 평가합니다. 슬러그는 고정되어 있어 분기 조건으로 써도 안전합니다.

슬러그	GARM 제목
adult_and_explicit_sexual_content	Adult & Explicit Sexual Content
arms_and_ammunition	Arms & Ammunition
crime_human_rights_violations	Crime & Harmful Acts, Human Rights Violations
death_injury_or_military_conflict	Death, Injury, or Military Conflict
online_piracy	Online Piracy
hate_speech_and_acts_of_aggression	Hate Speech & Acts of Aggression
obscenity_and_profanity	Obscenity & Profanity
illegal_drugs_alcohol_tobacco_vaping	Illegal Drugs / Tobacco / E-cigarettes / Vaping / Alcohol
spam_or_harmful_content	Spam or Harmful Content
terrorism	Terrorism
debated_sensitive_social_issue	Debated Sensitive Social Issue

검수 결과는 탐지된 카테고리를 심각도 레벨 없이 보고합니다. 각 garm[] 항목은 { category, reasoning }입니다.

Pyler 어휘

IAB와 GARM 외에, 일부 필드는 Pyler가 정의한 고정 어휘를 사용합니다.

필드	어휘
genre(영상)	영화·TV 장르 라벨 28개입니다. 영상마다 1~3개이며 주된 장르가 먼저 옵니다.
music_mood(장면)	calm, energetic, dramatic, playful, melancholic, tense, none.
weather(장면)	관찰된 날씨·하늘 상태 20개로, Indoor와 Unknown / Not visible을 포함합니다.
human_activity(장면)	자유 형식 action 슬러그에서 도출한 AVA-80 행동 라벨입니다.

판정 모델

브랜드 세이프티 검수는 block_decision에 결정론적인 판정 하나를 반환합니다.

block_decision	조건
block	GARM 카테고리가 하나 이상 탐지되었거나 정책 규칙이 하나 이상 일치했습니다.
allow	탐지된 카테고리도, 일치한 규칙도 없습니다.

API에는 중간 단계인 "review" 상태가 없습니다. 모델은 근거를 제공하고, 판정은 그 근거로 코드에서 계산합니다. 그래서 판정은 함께 반환되는 garm, blocklist.hits와 항상 일치합니다. 다만 근거 자체는 모델 출력이므로 틀릴 수 있습니다. block은 법적·정책적 결정이 아니라 "검토를 위한 보류"로 다루세요. 데이터 처리를 참고하세요.

garmobject[]

탐지된 GARM 카테고리이며 각각 { category, reasoning }입니다. 문제가 없으면 비어 있습니다. 규칙이 없어도 항상 평가합니다.

blocklistobject

{ rules, hits }입니다. rules는 평가한 모든 정책 줄입니다(팀에 저장된 차단 목록과 요청의 임시 rules). hits는 [{ rule, matched, evidence }]이며, matched: true인 항목이 일치한 규칙입니다.

explanationstring | null

탐지된 카테고리와 규칙을 앞에 붙인, 사람이 읽을 수 있는 한 문장 근거입니다. 표시용으로만 쓰고, 분기는 garm과 blocklist.hits로 하세요.

screening_failedboolean

검수 자체에서 오류가 났으면 true입니다. 이때 판정은 콘텐츠 판단이 아니라 예방 차원의 block(실패 시 차단)입니다. 재시도하고, 최종 사용자에게 실제 차단처럼 보여 주지 마세요.

경고

실제 차단과 검수 실패 모두 block_decision: "block"과 BLOCKED로 시작하는 explanation을 반환합니다. 텍스트가 아니라 screening_failed로 분기하세요.

정책 규칙

정책 규칙은 자연어 문장입니다("화면에서 음주 장면 금지"). 검수할 때마다 두 출처를 합칩니다.

• 대시보드의 Ad Blocking 탭에서 관리하는 팀의 저장된 차단 목록.
• 요청과 함께 보내는 임시 rules(쉼표 또는 줄바꿈으로 구분).

규칙마다 독립적으로 판단해 blocklist.hits에 보고합니다. 규칙은 GARM 위에 더하는 추가 정책이며, GARM 카테고리는 항상 평가합니다. API는 이 규칙 외에 사용자 정의 카테고리를 제공하지 않습니다.

판정을 반환하는 엔드포인트

엔드포인트	입력	참고
POST /api/v1/ad-blocking	멀티파트 파일 + 선택 입력 title, rules	동기 방식이며 몇 초 걸립니다. 소재 길이는 약 120초로 제한됩니다. 결과의 ad_id는 null입니다.
POST /api/v1.1/ad-blocking	JSON ad_id(+ rules)	등록된 소재를 검수합니다. ready가 아니면 409를 반환합니다.
GET /api/v1.1/ad-blocking	ad_id 필터	저장된 결과를 최신순으로 반환합니다. 클라이언트 타임아웃으로 놓친 판정은 다시 제출하지 말고 이 엔드포인트로 복구하세요.

전체 흐름은 브랜드 세이프티 가이드를 참고하세요.