본문 바로가기

개발자용 API

얼굴 유사도 비교 API

신분증 사진과 지금 찍은 셀피를 보내면 같은 사람일 가능성을 0~1 점수와 판정, 높음·보통·낮음 구간으로 돌려줍니다. 비대면 가입·계좌 개설·대여 서비스의 본인 확인 단계에 바로 붙이세요.

  • 신분증 진위 확인 뒤 본인 얼굴 대조까지 한 흐름으로
  • 판정 기준 점수를 서비스 위험도에 맞게 조절
  • 1장과 최대 10장을 한 번에 비교

서비스·시스템에 연동하는 기업·개발자를 위한 API입니다. 인증키로 호출하고 사용한 만큼 포인트가 차감됩니다.

이런 서비스에 연결합니다

  • 비대면 회원가입·계좌 개설신분증 진위 확인 뒤 신분증 사진과 셀피를 대조해 남의 신분증으로 가입하는 일을 막습니다.
  • 중고거래·차량 대여 본인 확인거래·대여 직전에 찍은 사진이 등록된 회원 사진과 같은 사람인지 확인합니다.
  • 출입·근태 사진 대조등록 사진 한 장과 현장 사진 여러 장(최대 10장)을 한 번에 비교해 가장 비슷한 사진을 찾습니다.

가격과 이용 조건

  • 비교 사진 1장 기준 10P · 2장째부터 1장당 5P
  • 얼굴을 찾지 못했거나 처리에 실패하면 차감하지 않습니다.
  • 가입하면 지급되는 무료 포인트로 바로 호출해 볼 수 있습니다.
  • 서비스·시스템에 연동하는 기업·개발자용 API입니다. 회원가입 후 발급되는 인증키로 호출합니다.
  • PNG·JPEG·WEBP·BMP 이미지를 받습니다. 얼굴이 정면으로 크게 나온 사진이 가장 정확합니다.
  • 보낸 사진은 비교가 끝나면 바로 지우며 저장하지 않습니다. 얼굴 특징값도 응답에 담지 않습니다.
  • 점수는 판단을 돕는 자료입니다. 정보주체의 동의를 받고, 최종 본인 확인 책임은 이용 서비스에 있습니다.

요금 정책 · 처음 연동 가이드

1분 소개 영상

호출 흐름

얼굴 유사도 비교 API 호출 흐름: ① 사진 2장 업로드(기준 사진과 비교 사진) → ② 얼굴 찾기(사진마다 대표 얼굴) → ③ 유사도 계산(0~1 점수) → ④ 결과 판정(같은 사람 여부). 높음은 통과, 보통은 다시 촬영, 낮음은 거절
  1. 신분증(또는 등록 사진)을 image, 지금 찍은 셀피를 compare_image로 보냅니다.
  2. 사진마다 가장 크게 나온 얼굴을 대표 얼굴로 고릅니다.
  3. 두 얼굴을 비교해 0~1 점수와 같은 사람 판정을 냅니다.
  4. 높음은 자동 통과, 보통은 재촬영·담당자 확인, 낮음은 거절로 나눕니다.

연동 예제

인증키는 Authorization: Bearer 헤더로 보냅니다. 서버에서만 호출하고 인증키를 브라우저·앱에 넣지 마세요.

cURL
curl -X POST "https://apick.app/rest/face_similarity" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@./id_card.jpg" \
  -F "compare_image=@./selfie.jpg"
Node.js (18 이상)
import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("image", new Blob([await readFile("./id_card.jpg")]), "id_card.jpg");
form.append("compare_image", new Blob([await readFile("./selfie.jpg")]), "selfie.jpg");

const response = await fetch("https://apick.app/rest/face_similarity", {
  method: "POST",
  headers: { Authorization: "Bearer " + process.env.APICK_API_KEY },
  body: form,
});
const { data, api } = await response.json();
if (data.error) throw new Error(data.error); // 실패는 과금되지 않습니다
console.log(data, api.cost);

응답 예시

{
  "data": {
    "similarity": 0.6213,
    "is_match": true,
    "level": "높음",
    "threshold": 0.4,
    "best_index": 1,
    "base_face": {
      "face_count": 1,
      "face_crop": [
        [
          288.4,
          61.2
        ],
        [
          370.9,
          168.7
        ]
      ],
      "det_score": 0.7762
    },
    "results": [
      {
        "index": 1,
        "face_found": true,
        "similarity": 0.6213,
        "is_match": true,
        "level": "높음",
        "face": {
          "face_count": 1,
          "face_crop": [
            [
              402.1,
              188.6
            ],
            [
              611.5,
              455
            ]
          ],
          "det_score": 0.8921
        }
      }
    ],
    "success": 1
  },
  "api": {
    "success": true,
    "cost": 10,
    "ms": 812
  }
}

예시 값입니다. 점수 구간과 판정 기준(threshold) 조절 방법은 개발 문서에 있습니다.

오류 해결

HTTP 상태 → api.success → data.error → api.cost 순서로 확인하세요. 실패 응답은 과금되지 않습니다.

  • 기준 이미지에서 얼굴을 찾지 못했습니다.HTTP 422

    얼굴이 정면으로 크게 나온 사진으로 바꿔 보내세요. 과금되지 않습니다.

  • 비교 이미지에서 얼굴을 찾지 못했습니다.HTTP 422

    보낸 비교 사진 모두에서 얼굴이 없을 때입니다. 셀피를 다시 찍게 하세요. 과금되지 않습니다.

  • 판정 기준(threshold)은 0.2 ~ 0.8 사이 숫자여야 합니다.HTTP 400

    threshold를 범위 안 숫자로 보내거나 생략하세요.

  • 유효하지 않은 API키 입니다.HTTP 401

    Authorization: Bearer 헤더의 인증키를 확인하세요. 인증키는 마이페이지에서 확인합니다.

  • 허용되지 않은 IP주소 입니다.HTTP 401

    마이페이지의 허용 IP 설정과 요청을 보내는 서버 IP를 확인하세요.

  • 사용 가능한 포인트이 부족합니다.HTTP 200

    HTTP 200이어도 data.error가 있으면 실패입니다. 포인트를 충전한 뒤 다시 요청하세요. 이 응답은 과금되지 않습니다.

전체 응답 항목과 오류 코드는 개발 문서에 있습니다.

키 발급 → 예제 실행 → 첫 성공까지 몇 분이면 됩니다.