Face Compare API

신분증 얼굴과 실제 촬영한 얼굴을 비교하여 두 이미지의 유사도를 반환합니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

요청 헤더

CLOVA eKYC API에서 공통으로 사용하는 헤더에 대한 정보는 CLOVA eKYC 요청 헤더를 참조해 주십시오.

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

Content-Type: application/json인 경우

Base64로 인코딩된 이미지를 전송할 때 사용합니다.

Content-Type: multipart/form-data인 경우

이미지 파일을 직접 업로드할 때 사용합니다.

요청 예시

요청 예시는 다음과 같습니다.

Content-Type: application/json인 경우

요청 헤더 Content-Type이 application/json인 경우, 요청 예시는 다음과 같습니다.

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/face/compare' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: application/json' \
--data '{
    "requestId": "request-001",
    "cardImage": {
      "name": "identification-card",
      "format": "jpg",
      "data": "{base64-encoded-image}"
    },
    "faceImage": {
      "name": "face",
      "format": "png",
      "data": "{base64-encoded-image}"
    }  
}'

Content-Type: multipart/form-data인 경우

요청 헤더 Content-Type이 multipart/form-data인 경우, 요청 예시는 다음과 같습니다.

curl --location --request POST 'https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/face/compare' \
--header 'X-EKYC-SECRET: {secret-key}' \
--header 'Content-Type: multipart/form-data' \
--form 'message={"requestId": "request-002", "cardImage": {"name":"card", "format":"jpg"}, "faceImage": {"name":"face", "format":"jpg"}}' \
--form 'cardImage=@"{image-file-path}"' \
--form 'faceImage=@"{image-file-path}"'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

faces

faces에 대한 설명은 다음과 같습니다.

응답 상태 코드

CLOVA eKYC API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 CLOVA eKYC 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

{
    "requestId": "request-001",
    "uid": "a1b2c3d4e5f6g7h8i9j0k1l2m3",
    "timestamp": 1700000000000,
    "result": "SUCCESS",
    "similarity": 0.40129185,
    "faces": [
    {
      "boundingPoly": {
        "vertices": [
          {
            "x": 366.07977,
            "y": 60.829987
          },
          {
            "x": 446.45795,
            "y": 60.829987
          },
          {
            "x": 446.45795,
            "y": 163.32437
          },
          {
            "x": 366.07977,
            "y": 163.32437
          }
        ]
      },
      "confidence": 0.9997929,
      "landmark": [
        {
          "type": "CHIN",
          "position": [
            363.64542,
            99.73236
          ]
        },
        {
          "type": "CHIN",
          "position": [
            446.89664,
            98.93187
          ]
        },
        {
          "type": "LEFT_EYEBROW",
          "position": [
            372.45084,
            90.12645
          ]
        },
        {
          "type": "LEFT_EYEBROW",
          "position": [
            376.4533,
            89.32596
          ]
        },
        {
          "type": "RIGHT_EYEBROW",
          "position": [
            415.67743,
            90.12645
          ]
        },
        {
          "type": "RIGHT_EYEBROW",
          "position": [
            415.67743,
            94.128914
          ]
        },
        {
          "type": "BRIDGE_OF_NOSE",
          "position": [
            406.07153,
            102.93434
          ]
        },
        {
          "type": "BRIDGE_OF_NOSE",
          "position": [
            405.27103,
            125.34814
          ]
        },
        {
          "type": "NOSE",
          "position": [
            396.4656,
            130.95158
          ]
        },
        {
          "type": "NOSE",
          "position": [
            414.87695,
            130.95158
          ]
        },
        {
          "type": "LEFT_EYE",
          "position": [
            377.25378,
            101.33335
          ]
        },
        {
          "type": "LEFT_EYE",
          "position": [
            382.05673,
            103.73483
          ]
        },
        {
          "type": "RIGHT_EYE",
          "position": [
            418.07892,
            105.335815
          ]
        },
        {
          "type": "RIGHT_EYE",
          "position": [
            422.08136,
            106.136314
          ]
        },
        {
          "type": "LIBS",
          "position": [
            390.06168,
            142.15848
          ]
        },
        {
          "type": "LIBS",
          "position": [
            394.06412,
            146.96144
          ]
        },
        {
          "type": "MOUTH",
          "position": [
            390.86215,
            142.15848
          ]
        },
        {
          "type": "MOUTH",
          "position": [
            398.0666,
            144.55995
          ]
        },
        {
          "type": "LEFT_PUPIL",
          "position": [
            386.0592,
            101.33335
          ]
        },
        {
          "type": "RIGHT_PUPIL",
          "position": [
            426.08383,
            102.93434
          ]
        }
      ],
      "alignedImage": "",
      "attributes": {
        "eulerAngle": {
          "pitch": -5.3966002,
          "roll": 1.0796471,
          "yaw": -1.540036,
          "pose": "front"
        }
      },
      "feature": [
        0.030027457,
        -0.045810863
      ]
    }
  ] // faces
}