{"openapi":"3.0.3","info":{"title":"APICK 이미지 얼굴 인식","version":"1.0.0","description":"이미지 한 장에서 사람 얼굴을 찾아 얼굴마다 위치(사각형 좌표)와 눈·코·입꼬리 좌표, 인식 점수를 돌려줍니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/face_detection":{"post":{"summary":"이미지 얼굴 인식","description":"이미지 한 장에서 사람 얼굴을 찾아 얼굴마다 위치(사각형 좌표)와 눈·코·입꼬리 좌표, 인식 점수를 돌려줍니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"result":{"type":"array","items":{"type":"object","properties":{"landmark":{"type":"array","items":{"type":"array","items":{"type":"number"}},"description":"얼굴 기준점 5개의 [x, y] 좌표입니다. 순서는 왼쪽 눈, 오른쪽 눈, 코, 왼쪽 입꼬리, 오른쪽 입꼬리입니다."},"height":{"type":"integer","description":"원본 이미지의 높이(픽셀)입니다."},"width":{"type":"integer","description":"원본 이미지의 너비(픽셀)입니다."},"det_score":{"type":"number","description":"얼굴일 가능성 0~1. 1에 가까울수록 확실한 얼굴입니다."},"face_crop":{"type":"array","items":{"type":"array","items":{"type":"number"}},"description":"얼굴 사각형의 [[왼쪽 위 x, y], [오른쪽 아래 x, y]] 좌표입니다. 사진을 얼굴 기준으로 자를 때 씁니다."}}},"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"},"threshold":{"type":"string","description":"얼굴 추출 민감도 (범위: 0 ~ 0.9, 기본값 0.5, 높을수록 정확한 얼굴만 추출) (string)"},"use_feature":{"type":"string","description":"얼굴 특징 정보를 응답에 포함할지 정합니다. 1은 포함, 0은 미포함(기본값)입니다. 특징 정보가 필요 없는 경우 0으로 두어 응답을 줄이세요. (string)"}},"required":["image"]}}}}}}},"x-code-tables":[{"title":"오류와 대처","columns":["HTTP","data.error","대처"],"rows":[["400","필수 입력값이 없습니다.","threshold를 0~0.9 사이 숫자로 보내세요."],["400","파일 유형이 맞지 않습니다. 이미지 형식의 파일만 허용됩니다.","이미지 파일인지 확인하세요."],["424","첨부파일이 없습니다.","파일 필드 이름을 image로 보냈는지 확인하세요."],["424","알 수 없는 이유로 실패했습니다.","이미지를 JPEG 또는 PNG로 다시 저장해 한 번 더 요청하세요."],["408","처리 시간 초과로 실패했습니다.","data.success가 3입니다. 이미지 해상도를 줄여 다시 요청하세요."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}