얼굴 대조 보고서: 유사도 점수 JSON

개요

얼굴 대조 보고서는 라이브니스 단계에서 캡처한 라이브 셀피와 기준 이미지(일반적으로 신분증 문서에서 추출한 인물 사진) 간의 1:1 생체 인식 비교 결과를 기록합니다. 0~100 사이의 단일 유사도 점수, 비교된 두 이미지에 대한 서명된 URL, 기준 이미지의 소스 세션, 대조 시 발생한 모든 경고를 반환합니다. 이 보고서는 사용자가 워크플로에서 라이브니스 단계와 문서 단계를 모두 완료한 후(생체 인증과 같은 인물 사진 기반 워크플로의 경우 라이브니스 단계만 완료한 후) 생성되거나, 임의의 두 얼굴 이미지를 직접 제공하는 독립 실행형 Face Match API를 통해 직접 생성됩니다. 각 보고서는 전체 세션 상태와 무관하게 고유한 status를 가지며, 이는 얼굴 대조 단계 자체의 처리 결과를 반영합니다.

승인됨 — score가 검토 임계값보다 높고 자동 거부 경고가 발생하지 않았습니다.
검토 중 — score가 거부 임계값과 검토 임계값 사이에 있거나, 점수를 계산할 수 없고 face_match_not_computed_action이 REVIEW로 설정되었습니다.
거부됨 — score가 거부 임계값 이하이거나, NO_REFERENCE_IMAGE가 발생했거나, 점수를 계산할 수 없고 face_match_not_computed_action이 DECLINE으로 설정되었습니다.
Resub Requested — 검토자가 콘솔에서 사용자에게 이 단계의 재제출을 요청했습니다.
Not Finished — 얼굴 대조 단계에서 아직 결과가 생성되지 않았습니다(사용자가 실패한 캡처를 재시도하는 중인 경우 포함).

API 응답에 표시되는 위치

얼굴 대조 보고서는 face_matches[] 배열 내에 포함되며, 단일 face_match 객체가 아닌 항상 JSON 배열 형태로 제공됩니다. 최소 하나 이상의 얼굴 대조 단계에서 데이터가 생성될 때까지는 null이며, 워크플로에서 얼굴 대조를 두 번 이상 실행하면 여러 항목이 나타납니다. Adaptive Age Verification 워크플로에서도 신분증 인증 대체 동작이 실행될 때 이 배열이 채워집니다. 해당 워크플로에는 자체 얼굴 대조 노드가 없으므로 이 항목은 연령 추정 노드를 node_id로 보고합니다.

세션 결정 API — GET /v3/session/{sessionId}/decision/은 최상위 수준에서 face_matches[]를 반환합니다. Retrieve session decision을 참조하세요.
webhook — 단계에서 데이터가 생성되면 session.status.updated payload에 동일한 face_matches[] 배열이 포함됩니다. Webhooks를 참조하세요.
독립 실행형 Face Match API — 직접 1:1 비교를 수행하려면 Face Match standalone API를 참조하세요.

response.face_matches[0]을 읽고 배열을 순회하세요. 일부 이전 튜토리얼에서 언급된 단일 face_match 형태는 v3 decision endpoint에 존재하지 않습니다.

스키마

필드별 표준 스키마는 Data models 참조 페이지에 있습니다. 아래 필드는 해당 표준 스키마를 반영합니다.

필드	타입	설명
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	얼굴 대조 단계 상태(`FeatureStatusChoices`).
`node_id`	string \| null	이 보고서를 생성한 워크플로 그래프 노드입니다.
`score`	number 0–100 \| null	소수점 둘째 자리로 반올림된 생체 인식 유사도 점수입니다. 비교할 수 없는 경우 `null`입니다.
`source_image_session_id`	string \| null	기준(소스) 이미지를 제공한 인물 사진이 저장된 세션의 UUID입니다. 인물 사진 기반 플로우(생체 인증 또는 세션 생성 시 제공된 인물 사진)에서 설정됩니다. 기준 이미지가 동일한 세션에서 캡처된 신분증 인물 사진인 경우 `null`입니다.
`source_image`	string (서명된 URL)	기준 이미지(일반적으로 신분증 인물 사진)입니다. 수명이 짧은 서명된 URL이므로 즉시 다운로드해야 하며 URL을 저장하지 마세요.
`target_image`	string (서명된 URL)	대상 이미지(일반적으로 라이브니스 셀피)입니다. 수명이 짧은 서명된 URL이므로 즉시 다운로드해야 하며 URL을 저장하지 마세요.
`warnings[]`	array	모듈 수준 경고입니다. 각 항목에는 `feature`(항상 `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`가 포함됩니다. Face match warnings를 참조하세요.

상태 값

상태	의미	후속 영향
`Approved`	점수가 검토 임계값보다 높고 자동 거부 경고가 발생하지 않았습니다.	성공한 얼굴 대조로 처리됩니다.
`In Review`	점수가 거부 임계값보다 높지만 검토 임계값 이하이거나, `face_match_not_computed_action`이 `REVIEW`로 설정된 상태에서 점수를 계산할 수 없는 경우(예: 기준 이미지가 남지 않는 비문서 조회 후 `FACE_MATCH_NOT_COMPUTED`)입니다.	검토자가 조치할 때까지 세션도 `In Review`로 전환됩니다.
`Declined`	점수가 거부 임계값 이하이거나, `NO_REFERENCE_IMAGE`가 발생했거나, `face_match_not_computed_action`이 `DECLINE`으로 설정된 상태에서 점수를 계산할 수 없는 경우입니다.	다른 승인된 분기가 워크플로를 충족하지 않는 한 세션이 거부됩니다.
`Resub Requested`	검토자가 콘솔에서 이 단계의 재제출을 요청했습니다.	사용자에게 다시 캡처하도록 요청합니다.
`Not Finished`	얼굴 대조 단계에서 결과가 생성되지 않았습니다(입력값이 누락되었거나, 워크플로가 비교 단계에 도달하지 않았거나, 사용자가 여전히 캡처 재시도 루프에 있는 경우).	분기가 완료되지 않았습니다.

유사도가 낮아 실패한 경우 상태가 확정되기 전에 재시도됩니다. 사용자는 최대 face_match_max_attempts회(기본값 3회)까지 캡처할 수 있으며 최종 시도의 점수만 적용됩니다. 워크플로 노드에 구성된 커스텀 상태 규칙에 따라 결과 상태를 추가로 조정할 수 있으며, Declined > In Review > Approved 우선순위에 따라 점수 기반 상태와 결합됩니다.

예시

승인됨 — 정상 일치

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

검토 중 — 경계선 유사도

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

거부됨 — 대조할 기준 이미지 없음

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

보안 참고 사항

source_image 및 target_image에 대한 서명된 URL은 생체 인식 데이터이며 짧은 유효 기간이 지나면 만료됩니다. 이를 수명이 짧은 URL로 취급하여 캐시하거나 공개적으로 노출하지 마세요. 일반적으로 애플리케이션에는 status와 score만 필요하므로, 서버의 생체 인식 데이터를 최소화할 수 있도록 가능한 한 적게 저장하세요.

인증

인증

모니터링

플랫폼

얼굴 대조 보고서: 유사도 점수 JSON

개요

API 응답에 표시되는 위치

스키마

상태 값

예시

승인됨 — 정상 일치

검토 중 — 경계선 유사도

거부됨 — 대조할 기준 이미지 없음

보안 참고 사항

관련 항목

​개요

​API 응답에 표시되는 위치

​스키마

​상태 값

​예시

​승인됨 — 정상 일치

​검토 중 — 경계선 유사도

​거부됨 — 대조할 기준 이미지 없음

​보안 참고 사항

​관련 항목

개요

API 응답에 표시되는 위치

스키마

상태 값

예시

승인됨 — 정상 일치

검토 중 — 경계선 유사도

거부됨 — 대조할 기준 이미지 없음

보안 참고 사항

관련 항목