개요
얼굴 검색은 팀에서 검색 결과가Approved 또는 Declined로 반환된 이유를 파악할 수 있도록 몇 가지 경고를 생성합니다. 경고는 POST /v3/face-search/ 응답의 face_search.warnings[] 배열로 반환됩니다(얼굴 검색 보고서 참조).
이곳의 경고는 워크플로 경고에 비해 축소된 형태를 사용합니다. 즉, node_id가 없습니다. 문서화된 응답 명세는 risk, additional_data, log_type, short_description, long_description의 5개 필드를 선언하며, 런타임 payload에는 추가로 feature가 포함되는데 이 endpoint에서는 항상 "LIVENESS"입니다.
생성되는 경고
생성자:
FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); 상태 도출: get_face_search_status (apis/views/face_search.py:242-248), 이는 두 가지 차단 목록 위험에 대해서만 거부합니다.
알아두어야 할 생성 규칙:
- 차단 목록이 중복보다 우선합니다. 확인된 차단 목록 일치는
DUPLICATED_FACE를 억제하고, 가능한 차단 목록 일치는POSSIBLE_DUPLICATED_FACE를 억제합니다. 즉, 동일한 신뢰도 구간에 대해 한 쌍의 두 구성원을 모두 받는 일은 없습니다. additional_data는 일치하는 첫 번째 얼굴만 참조합니다(matches[]에 여러 개가 포함되어 있더라도 마찬가지입니다). 차단 목록 경고에는{blocklisted_session_id, blocklisted_session_number, api_service}가 포함되고, 중복 경고에는{duplicated_session_id, duplicated_session_number, api_service}가 포함되며,MULTIPLE_FACES_DETECTED에는null이 포함됩니다.api_service값은 대문자(예:PASSIVE_LIVENESS)이거나 워크플로 세션의 경우null입니다.- 허용 목록에 있는 얼굴은 중복 경고를 억제합니다 — 높은 신뢰도의 허용 목록 일치는
DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE를 제거합니다(차단 목록 경고는 절대 제거하지 않습니다).
정확한 경고 문자열
검색 이미지 게이트
user_image에서 얼굴이 감지되지 않으면 API는 face_search 객체가 생성되기 전에 HTTP 400 및 {"error": "No face detected in the image"}로 요청을 거부합니다. 따라서 성공한 얼굴 검색 응답에는 NO_FACE_DETECTED 경고가 절대 나타나지 않습니다. 이는 warnings[]가 아닌 최상위 error 문자열로 반환됩니다.
구성 가능한 설정
확인된 일치 항목(FACE_IN_BLOCKLIST, DUPLICATED_FACE)과 가능한 일치 항목(POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE)을 구분하는 유사도 구간은 내부적으로 고정되어 있습니다. 애플리케이션별 임계값 조정은 이 endpoint가 아닌 워크플로 라이브니스 확인에 적용됩니다. 요청별로 제어할 수 있는 스위치는 다음과 같습니다.
search_type(most_similar, 기본값 |blocklisted_or_approved) —most_similar는 등록된 모든 얼굴을 유사도순으로 순위를 매깁니다.blocklisted_or_approved는 후보를 차단 목록에 등록된 얼굴, 허용 목록에 등록된 얼굴, 승인된 세션의 얼굴, 가져온 사용자 프로필 얼굴로 제한하며 차단 목록 항목의 순위를 먼저 매깁니다.save_api_request(기본값true) — 호출을 API 유형 세션으로 저장하고 검색된 얼굴을 얼굴 검색 색인에 등록합니다. 얼굴 검색 호출로 등록된 얼굴은 향후 얼굴 검색 결과에서 제외됩니다. 저장하거나 등록하지 않고 조회하려면false로 설정합니다.rotate_image(기본값false) — 90도 회전을 시도하고 얼굴 감지가 가장 잘 된 방향을 유지합니다. EXIF 방향 정보가 누락되었을 때 유용합니다.
예시
차단 목록 일치 (Declined로 강제 설정됨)
중복 신호 (상태는 Approved로 유지됨)
관련 항목
- Face Search 보고서 — 전체 응답 형태
- Face Search API 참조 — 요청 파라미터
- Face Match 경고 — 셀피와 문서 간 1:1 대조 경고(Face Search와 별개)
- 데이터 모델 — Face Search — 표준 스키마