메인 콘텐츠로 건너뛰기

콜백 응답 예시

콜백 응답 예시 섹션은 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: 임계값 기준으로 두 얼굴이 일치하는지 나타내는 불리언 값

오류 응답

연동 가이드

  1. 콜백 엔드포인트를 설정해 POST 요청을 받을 수 있게 합니다
  2. transactionId를 검증해 올바른 응답을 처리하고 있는지 확인합니다
  3. statusCode를 확인해 요청 성공 여부를 판단합니다
  4. result 객체를 파싱해 유사도 점수와 얼굴 감지 데이터를 추출합니다
  5. 응답에 error 객체가 있는지 확인해 오류를 안전하게 처리합니다

모범 사례

  • transactionId로 멱등성을 구현해 중복 처리를 방지합니다
  • 콜백 엔드포인트에 적절한 타임아웃을 설정합니다
  • 디버깅과 모니터링을 위해 모든 응답을 로그로 남깁니다
  • 데이터를 처리하기 전에 응답 구조를 검증합니다
  • 네트워크 오류를 처리하고 필요하면 재시도 로직을 구현합니다

관련 문서

얼굴 비교 개요

얼굴 유사도 분석을 위한 얼굴 비교 API에 대해 알아보기

Face Compare API

두 얼굴 이미지를 비교해 유사도 점수를 반환하는 얼굴 비교 API 레퍼런스입니다.