콜백 응답 예시
콜백 응답 예시 섹션은 API 연동 시 받게 될 응답 샘플을 보여 주어 응답 구조와 형식을 명확히 이해할 수 있게 합니다. 이 예시를 활용하면 연동을 효과적으로 개발·테스트하고, 애플리케이션과 API 간 통신을 원활하게 만들 수 있습니다. 이 섹션은 연동 과정을 개선하고 개발 작업을 간소화하는 데 유용한 자료입니다.개요
Face Compare API를 콜백 URL과 함께 사용하면 시스템이 요청을 비동기로 처리하고 결과를 지정한 콜백 엔드포인트로 보냅니다. 이 방식은 일괄 처리나, 애플리케이션을 막지 않고 여러 요청을 처리해야 할 때 적합합니다.응답 구조
콜백 응답에는 다음 주요 구성 요소가 포함됩니다.- statusCode: 결과를 나타내는 HTTP 상태 코드
- apiType: API 유형 식별자 (“compare_face”)
- transactionId: 요청 추적용 고유 식별자
- result: 상세 비교 결과를 담은 객체
응답 샘플
응답 필드
상태 정보
- statusCode: HTTP 상태 코드 (성공 시 200)
- apiType: 이 API에서는 항상 “compare_face”
- transactionId: 고유 트랜잭션 식별자
얼굴 인식 결과
- isAvailable: 얼굴이 감지되었는지 나타내는 불리언 값
- boundingBox: 감지된 얼굴의 좌표
- Width: 바운딩 박스 너비 (0~1 범위)
- Height: 바운딩 박스 높이 (0~1 범위)
- Left: 바운딩 박스 왼쪽 좌표 (0~1 범위)
- Top: 바운딩 박스 위쪽 좌표 (0~1 범위)
- confidence: 얼굴 감지 신뢰도 점수 (0~1 범위)
유사도 분석
- score: 두 얼굴 간 유사도 점수 (0~1 범위)
- threshold: 일치 판단에 쓰는 임계값 (일반적으로 0.8)
- isMatch: 임계값 기준으로 두 얼굴이 일치하는지 나타내는 불리언 값
오류 응답
연동 가이드
- 콜백 엔드포인트를 설정해 POST 요청을 받을 수 있게 합니다
- transactionId를 검증해 올바른 응답을 처리하고 있는지 확인합니다
- statusCode를 확인해 요청 성공 여부를 판단합니다
- result 객체를 파싱해 유사도 점수와 얼굴 감지 데이터를 추출합니다
- 응답에 error 객체가 있는지 확인해 오류를 안전하게 처리합니다
모범 사례
- transactionId로 멱등성을 구현해 중복 처리를 방지합니다
- 콜백 엔드포인트에 적절한 타임아웃을 설정합니다
- 디버깅과 모니터링을 위해 모든 응답을 로그로 남깁니다
- 데이터를 처리하기 전에 응답 구조를 검증합니다
- 네트워크 오류를 처리하고 필요하면 재시도 로직을 구현합니다
관련 문서
얼굴 비교 개요
얼굴 유사도 분석을 위한 얼굴 비교 API에 대해 알아보기
Face Compare API
두 얼굴 이미지를 비교해 유사도 점수를 반환하는 얼굴 비교 API 레퍼런스입니다.