{"openapi":"3.0.3","info":{"title":"APICK 얼굴 유사도 비교","version":"1.0.0","description":"기준 사진과 비교 사진에서 대표 얼굴을 찾아 같은 사람일 가능성을 0~1 점수, 같은 사람 판정(is_match), 점수 구간(높음·보통·낮음)으로 돌려줍니다. 신분증 사진과 셀피를 대조하는 비대면 본인 확인에 맞춰 만들었습니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/face_similarity":{"post":{"summary":"얼굴 유사도 비교","description":"기준 사진과 비교 사진에서 대표 얼굴을 찾아 같은 사람일 가능성을 0~1 점수, 같은 사람 판정(is_match), 점수 구간(높음·보통·낮음)으로 돌려줍니다. 신분증 사진과 셀피를 대조하는 비대면 본인 확인에 맞춰 만들었습니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"similarity":{"type":"number","description":"가장 비슷한 비교 사진의 점수 0~1입니다. 1에 가까울수록 같은 사람일 가능성이 높습니다."},"is_match":{"type":"boolean","description":"점수가 threshold 이상이면 true입니다."},"level":{"type":"string","description":"점수 구간 높음·보통·낮음입니다."},"threshold":{"type":"number","description":"이번 판정에 쓴 기준 점수입니다."},"best_index":{"type":"integer","description":"가장 비슷한 비교 사진 번호(1부터)입니다. 비교 사진이 1장이면 1입니다."},"base_face":{"type":"object","properties":{"face_count":{"type":"integer","description":"사진에서 찾은 얼굴 수입니다."},"face_crop":{"type":"array","items":{"type":"array","items":{"type":"number"}},"description":"대표 얼굴 사각형의 [[왼쪽 위 x, y], [오른쪽 아래 x, y]] 픽셀 좌표입니다."},"det_score":{"type":"number","description":"얼굴일 가능성 0~1입니다."}},"description":"기준 사진에서 고른 대표 얼굴입니다."},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"비교 사진 번호(1부터)입니다."},"face_found":{"type":"boolean","description":"이 사진에서 얼굴을 찾았는지 여부입니다. false이면 점수·판정이 비어 있습니다."},"similarity":{"type":"number","description":"기준 얼굴과의 점수입니다. 얼굴이 없으면 null입니다.","nullable":true},"is_match":{"type":"boolean","description":"이 사진의 같은 사람 판정입니다."},"level":{"type":"string","description":"이 사진의 점수 구간입니다. 얼굴이 없으면 null입니다.","nullable":true},"face":{"type":"object","properties":{"face_count":{"type":"integer"},"face_crop":{"type":"array","items":{"type":"array","items":{"type":"number"}}},"det_score":{"type":"number"}},"description":"이 사진의 대표 얼굴(face_count·face_crop·det_score)입니다."}}},"description":"비교 사진마다의 결과입니다. 보낸 순서대로 담깁니다."},"success":{"type":"integer","description":"처리 결과입니다. 1: 성공(과금), 0: 실패, 3: 시간 초과(과금 없음)."}},"description":"비교 결과"},"api":{"type":"object","properties":{"success":{"type":"boolean","description":"요청을 정상 처리했는지 여부입니다."},"cost":{"type":"integer","description":"이번 요청에서 차감된 포인트입니다."},"ms":{"type":"integer","description":"처리 시간(밀리초)입니다."},"pl_id":{"type":"integer","description":"결제 기록 번호입니다. 문의할 때 함께 알려 주세요."}},"description":"호출 공통 정보"}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"분석할 이미지 파일입니다. JPG·PNG·WEBP를 지원하며, 파일 크기·해상도 제한은 요청 표를 확인하세요. (file)","format":"binary"},"compare_image":{"type":"string","description":"비교 사진입니다. 지금 찍은 셀피를 보냅니다. 여러 장을 비교하려면 아래 번호 붙은 이름을 함께 쓰거나 대신 씁니다. (file)","format":"binary"},"compare_image1":{"type":"string","description":"여러 장 비교의 첫 번째 사진입니다. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다. (file)","format":"binary"},"compare_image2":{"type":"string","description":"여러 장 비교의 두 번째 사진입니다. 같은 방식으로 compare_image10까지, 비교 사진은 모두 합쳐 최대 10장입니다. (file)","format":"binary"},"threshold":{"type":"string","description":"같은 사람으로 판정할 기준 점수 (범위: 0.2 ~ 0.8, 기본값 0.4, 높을수록 엄격) (string)"}},"required":["image","compare_image"]}}}}}}},"x-code-tables":[{"title":"오류와 대처","columns":["HTTP","data.error","대처"],"rows":[["400","기준 이미지(image)가 없습니다.","기준 사진을 image 필드로 보내세요."],["400","비교 이미지(compare_image)가 없습니다.","비교 사진을 compare_image 또는 compare_image1 필드로 보내세요."],["400","비교 이미지는 한 번에 10장까지 보낼 수 있습니다.","10장씩 나눠 요청하세요."],["400","이미지 형식의 파일만 보낼 수 있습니다.","PNG·JPEG·WEBP·BMP 이미지인지 확인하세요."],["400","판정 기준(threshold)은 0.2 ~ 0.8 사이 숫자여야 합니다.","threshold를 범위 안 숫자로 보내거나 생략하세요."],["422","기준 이미지에서 얼굴을 찾지 못했습니다. …","얼굴이 정면으로 크게 나온 사진으로 바꿔 보내세요. 신분증은 빛 반사가 없게 찍습니다."],["422","비교 이미지에서 얼굴을 찾지 못했습니다. …","보낸 비교 사진 모두에서 얼굴이 없을 때입니다. 셀피를 다시 찍게 하세요."],["424","얼굴을 비교하지 못했습니다. 잠시 후 다시 시도해 주세요.","잠시 뒤 한 번 더 요청하세요."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}