버전
| 날짜 | 변경사항 |
|---|---|
| 2023-11-23 | 최초 작성 |
개요
얼굴 비교 API 가이드입니다. 신분증의 얼굴과 실제 얼굴을 촬영하고 두 이미지를 비교하여 유사도를 반환합니다.
요청
| 메서드 | 요청 URI |
|---|---|
| POST | - API 연동설정의 InvokeURL 과 API 경로의 조합으로 호출 - 각 도메인마다 고유의 호출 URL이 생성됨 |
API URL 예시
- {invokeUrl}/compare
- https://{apigwId}.apigw-pub.fin-ntruss.com/ekyc/v1/{domainId}/{signature}/face/compare
요청 헤더
| 이름 | 설명 |
|---|---|
| X-EKYC-SECRET | API 연동설정에서 생성한 X-EKYC-SECRET:{Client Secret} |
| Content-Type | application/json : 이미지는 image.data 필드에 base64 인코딩을 하여 전송 multipart/form-data: 이미지를 파일로 전송 |
요청 바디
Content-Type : application/json
- 이미지 인식 요청
요청 필드
| 필드이름 | 필수여부 | 데이터유형 | 설명 | 제약사항 |
|---|---|---|---|---|
| requestId | Yes | string | API 호출 ID | 동일한 requestId 는 10분간 재사용 불가 |
| cardImage | Yes | object | 신분증 이미지 정보 | |
| cardImage.format | Yes | string | 이미지 포맷 설정 | 'jpg', 'jpeg', 'png' 이미지, 'pdf', 'tiff' 단일 페이지 형식 지원 |
| cardImage.data | Yes | string | base64 인코딩 이미지 바이트 | |
| cardImage.name | Yes | string | - 이미지명 입력 - 이미지를 식별 및 응답 결과 확인에 사용됨 |
|
| faceImage | Yes | object | 얼굴 이미지 정보 | |
| faceImage.format | Yes | string | 이미지 포맷 설정 | 'jpg', 'jpeg', 'png' 이미지, 'pdf', 'tiff' 단일 페이지 형식 지원 |
| faceImage.data | Yes | string | base64 인코딩 이미지 바이트 | |
| faceImage.name | Yes | string | - 이미지명 입력 - 이미지를 식별 및 응답 결과 확인에 사용됨 |
CURL example:
curl -X POST '{invokeUrl}/compare' \
-H 'X-EKYC-SECRET: {secretKey}' \
-d '{"cardImage": {"format":"jpg","name":"card","data":"{base64Bytes}"}, "faceImage": {"format":"jpg","name":"face","data":"{base64Bytes}"}, "requestId":"string"}'
Content-Type : multipart/form-data
- 이미지 인식 요청
| 필드이름 | 필수여부 | 예시 |
|---|---|---|
| message | Y | {"requestId": "string", "cardImage": {"format":"jpg","name":"card"}, "faceImage": {"format":"jpg","name":"face"}} |
| cardImage | Y | 이미지 파일 |
| faceImage | Y | 이미지 파일 |
참고
message 상세는 application/json 요청과 동일
CURL example:
curl -X POST '{invokeUrl}/compare' \
-H 'X-EKYC-SECRET: {secretKey}' \
-F 'message={"requestId":"string", "cardImage": {"format":"jpg","name":"card"}, "faceImage": {"format":"jpg","name":"face"}}' \
-F 'cardImage=@card.png' \
-F 'faceImage=@face.png'
응답
응답바디
| 필드이름 | 데이터유형 | 설명 |
|---|---|---|
| requestId | string | 요청ID |
| timestamp | integer | 응답 timestamp |
| uid | string | 내부 UUID |
| result | string | 인식결과: SUCCESS, ERROR |
| message | string | 결과메시지 |
| faces | array object | 인식된 얼굴정보 |
| similarity | number | 유사도: 0 ~ 1 사이의값 |
- face 상세
| 필드이름 | 데이터유형 | 설명 |
|---|---|---|
| faces | array object | 얼굴인식결과 |
| faces[].boundingPoly | BoundingPoly[] | 얼굴영역 |
| faces[].confidence | float | 신뢰도 |
| faces[].landmark | array object | 랜드마크 정보 |
| faces[].landmark.type | string | 랜드마크 유형 |
| faces[].landmark.position | float[] | 위치 |
| faces[].alignedImage | string | 정렬된 이미지 |
| faces[].attributes | object | 속성 정보 |
| faces[].attributes.eulerAngle | object | 오일러 각 |
| faces[].attributes.eulerAngle.pitch | float | Pitch(Tilt) |
| faces[].attributes.eulerAngle.roll | float | Roll |
| faces[].attributes.eulerAngle.yaw | float | Yaw(Pan) |
| faces[].attributes.eulerAngle.pose | string | Pose |
| faces[].attributes.maskOption | object | 마스크를 썼는지에 대한 속성 |
| faces[].attributes.maskOption.isWearing | boolean | 여부 |
| faces[].feature | float[] | 특징 정보 |
응답 예시
{
"requestId": "af07a98e-f117-4e20-811d-5d902444145e",
"uid": "cc987492e03146029046ff749fd76de9",
"timestamp": 1700045064132,
"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
}