REST APIv1.0

FIDOX REST API

HTTP 호출로 얼굴 인식 기능을 연동하세요.

curl, Python, JavaScript 등 어떤 언어에서든 사용할 수 있습니다.

빠른 시작

터미널에서 2개 명령어만 실행하면 바로 결과를 확인할 수 있습니다.

1토큰 발급

API 키로 인증 토큰을 발급받습니다. 토큰은 1시간 유효합니다.

2두 얼굴 비교

이미지 2장을 base64로 변환 후 compare API를 호출합니다.

# 1. 토큰 발급
TOKEN=$(curl -s -X POST https://api.fidox.co/auth/client/token \
  -H "Content-Type: application/json" \
  -d '{"accessKey":"여기에-access-key","secretKey":"여기에-secret-key"}' \
  | grep -o '"token":"[^"]*"' | cut -d'"' -f4)

# 2. 두 얼굴 비교
IMG1=$(base64 -i photo1.jpg | tr -d '\n')
IMG2=$(base64 -i photo2.jpg | tr -d '\n')
echo '{"image1":"'$IMG1'","image2":"'$IMG2'"}' > /tmp/req.json

curl -s -X POST https://api.fidox.co/face/compare \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json | python3 -m json.tool
Response
{
  "success": true,
  "txId": "tx_abc123def456",
  "score": 0.92,       ← 유사도 (0~1, 높을수록 비슷)
  "matched": true,     ← 동일인 여부
  "code": "00000",
  "message": "OK"
}

연동 흐름

1

API 키 발급

app.fidox.co에서 Access Key / Secret Key 발급

2

토큰 발급

API 키로 인증 토큰 발급 (1시간 유효)

3

API 호출

토큰을 헤더에 넣고 JSON으로 요청

JavaScript
const tokenRes = await fetch('https://api.fidox.co/auth/client/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    accessKey: 'your-access-key',
    secretKey: 'your-secret-key',
  }),
});
const { token } = await tokenRes.json();

const res = await fetch('https://api.fidox.co/face/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({
    userCode: 'user-001',
    image: base64String,
  }),
});
const result = await res.json();
console.log(result.matched, result.score);

인증

모든 API 호출에는 Bearer 토큰이 필요합니다. API 키로 토큰을 발급받고, 이후 모든 요청 헤더에 포함하세요.

유효기간 1시간— 만료 시 동일 방법으로 재발급
언어 무관— curl, Python, Java, Go 등
Base URLhttps://api.fidox.co
POST/auth/client/token
파라미터설명
accessKey필수API Access Key
secretKey필수API Secret Key
curl -X POST https://api.fidox.co/auth/client/token \
  -H "Content-Type: application/json" \
  -d '{"accessKey":"your-access-key","secretKey":"your-secret-key"}'
Response
{
  "token": "eyJhbGciOiJIUzI1NiIs..."
}

→ 이후 모든 요청에 헤더 추가:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

이미지 형식

모든 이미지는 Base64 문자열로 전달합니다. JPEG, PNG 지원, 이미지 1장당 최대 10MB.

Base64란?

이미지(바이너리)를 텍스트 문자열로 변환한 것입니다. JSON으로 이미지를 전송하려면 Base64 변환이 필요합니다.

curl 사용 시 Base64 문자열이 길어질 수 있으므로, JSON 파일로 저장 후 -d @파일경로로 전송하세요.

JSON 파일로 전송 (권장)

curl
# 1. 이미지를 base64로 변환
BASE64=$(base64 -i face.jpg | tr -d '\n')

# 2. JSON 파일로 저장
echo '{"userCode":"user-001","image":"'$BASE64'"}' > /tmp/req.json

# 3. 파일로 요청
curl -s -X POST https://api.fidox.co/face/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json | python3 -m json.tool

언어별 Base64 변환

IMG=$(base64 -i face.jpg | tr -d '\n')

얼굴 인식 API

등록, 인증, 식별, 비교, 카운트, 삭제 기능을 제공합니다.

POST/face/register

사용자 얼굴을 등록합니다. verify(인증)나 identify(식별) 사용 전에 먼저 등록이 필요합니다. 이미 등록된 userCode로 재등록 시 FR004 에러. 채널 설정에 따라 동일 얼굴 중복 등록도 차단됩니다(FR008).

파라미터설명
userCode필수사용자 고유 코드 (사번, 회원ID 등)
image필수얼굴 사진 (Base64)
name사용자 이름 (선택)
consent생체정보 동의 여부 (채널 설정 requireConsent=true 시 필수)
BASE64=$(base64 -i face.jpg | tr -d '\n')
echo '{"userCode":"user-001","image":"'$BASE64'","name":"홍길동"}' > /tmp/req.json

curl -s -X POST https://api.fidox.co/face/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json | python3 -m json.tool
Response
{
  "success": true,
  "txId": "tx_abc123def456",
  "code": "00000",
  "message": "OK"
}
POST/face/verify

등록된 얼굴과 비교하여 본인이 맞는지 확인합니다. 출퇴근, 로그인 등에 사용합니다.

파라미터설명
userCode필수확인할 사용자 코드
image필수현재 얼굴 사진 (Base64)
contextlogin | monitoring | general
withLivenesstrue 시 실제 사람인지 검사 (사진 공격 방지)
BASE64=$(base64 -i face.jpg | tr -d '\n')
echo '{"userCode":"user-001","image":"'$BASE64'","context":"login"}' > /tmp/req.json

curl -s -X POST https://api.fidox.co/face/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json | python3 -m json.tool
Response
{
  "success": true,
  "txId": "tx_abc123def456",
  "score": 0.95,
  "matched": true,
  "threshold": 0.7,
  "code": "00000",
  "message": "OK",
  "liveness": {          ← withLiveness=true 시에만
    "isLive": true,
    "score": 0.99,
    "threshold": 0.5
  }
}
POST/face/identify

등록된 전체 얼굴 DB에서 일치하는 사용자를 찾습니다. userCode 없이 이미지만 전송합니다.

파라미터설명
image필수얼굴 사진 (Base64)
withLivenessliveness 검증 포함 (기본 false)
BASE64=$(base64 -i face.jpg | tr -d '\n')
echo '{"image":"'$BASE64'"}' > /tmp/req.json

curl -s -X POST https://api.fidox.co/face/identify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json | python3 -m json.tool
Response
{
  "success": true,
  "txId": "tx_abc123def456",
  "score": 0.92,
  "matched": true,
  "uid": "user-001",
  "name": "홍길동",
  "code": "00000",
  "message": "OK"
}
POST/face/compare

두 이미지의 얼굴을 1:1 비교합니다. 사전 등록 없이 바로 사용 가능합니다.

파라미터설명
image1필수첫 번째 얼굴 사진 (Base64)
image2필수두 번째 얼굴 사진 (Base64)
IMG1=$(base64 -i photo1.jpg | tr -d '\n')
IMG2=$(base64 -i photo2.jpg | tr -d '\n')
echo '{"image1":"'$IMG1'","image2":"'$IMG2'"}' > /tmp/req.json

curl -s -X POST https://api.fidox.co/face/compare \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json | python3 -m json.tool
Response
{
  "success": true,
  "txId": "tx_abc123def456",
  "score": 0.92,
  "matched": true,
  "code": "00000",
  "message": "OK"
}
POST/face/count

이미지에서 얼굴 수를 세고, 각 얼굴의 위치 좌표를 반환합니다.

파라미터설명
image필수사진 (Base64)
BASE64=$(base64 -i group-photo.jpg | tr -d '\n')
echo '{"image":"'$BASE64'"}' > /tmp/req.json

curl -s -X POST https://api.fidox.co/face/count \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json | python3 -m json.tool
Response
{
  "success": true,
  "txId": "tx_abc123def456",
  "faceCnt": 3,
  "faces": [[10,20,100,100], ...],  ← [x, y, w, h]
  "code": "00000",
  "message": "OK"
}
DELETE/face/:userCode

등록된 얼굴 데이터를 삭제합니다. URL 경로에 userCode를 넣으세요.

curl -X DELETE https://api.fidox.co/face/user-001 \
  -H "Authorization: Bearer $TOKEN"
Response
{
  "success": true,
  "txId": "tx_abc123def456",
  "code": "00000",
  "message": "OK"
}

전체 예제

복사해서 바로 실행할 수 있는 완전한 코드입니다. API 키만 바꾸면 동작합니다.

AK="your-access-key"
SK="your-secret-key"
IMG="face.jpg"

TOKEN=$(curl -s -X POST https://api.fidox.co/auth/client/token \
  -H "Content-Type: application/json" \
  -d "{\"accessKey\":\"$AK\",\"secretKey\":\"$SK\"}" \
  | grep -o '"token":"[^"]*"' | cut -d'"' -f4)
echo "토큰: $TOKEN"

BASE64=$(base64 -i $IMG | tr -d '\n')

echo "\n== 얼굴 등록 =="
echo '{"userCode":"test-user","image":"'$BASE64'"}' > /tmp/req.json
curl -s -X POST https://api.fidox.co/face/register \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json

echo "\n\n== 얼굴 인증 =="
curl -s -X POST https://api.fidox.co/face/verify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d @/tmp/req.json

echo "\n\n== 얼굴 삭제 =="
curl -s -X DELETE https://api.fidox.co/face/test-user \
  -H "Authorization: Bearer $TOKEN"
echo ""

에러 처리

API 에러 응답은 HTTP 상태 코드와 에러 코드를 포함합니다.

HTTP 상태 코드

코드의미대응
200성공정상 처리됨
400잘못된 요청필수 파라미터 확인
401인증 실패토큰 재발급
429한도 초과잠시 후 재시도
500서버 오류기술 지원 문의

에러 코드

코드설명
FR001얼굴 감지 불가
FR002복수 얼굴 감지
FR003미등록 사용자
FR004이미 등록된 사용자
FR005이미지 품질 부족
FR006FR 엔진 사용 불가
FR007라이브니스 실패 (스푸핑 감지)
FR008중복 얼굴 감지 (다른 사용자로 동일 얼굴 등록 시도)
FR009생체정보 동의 필요 (consent 미전달)
AUTH001인증 실패
LIMIT001API 호출 한도 초과
Response
{
  "statusCode": 400,
  "errorCode": "FR001",
  "message": "Face not detected in image"
}

에러 핸들링

const res = await fetch('https://api.fidox.co/face/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`,
  },
  body: JSON.stringify({ userCode: 'user', image }),
});

if (!res.ok) {
  const error = await res.json();
  if (res.status === 401) {
    token = await getNewToken();
  }
  switch (error.errorCode) {
    case 'FR001':
      alert('얼굴이 잘 보이는 사진을 올려주세요');
      break;
    case 'FR003':
      alert('등록되지 않은 사용자입니다');
      break;
    default:
      alert(`오류: ${error.message}`);
  }
}

OpenAPI

OpenAPI 3.0 스펙을 제공합니다. Swagger UI에서 바로 테스트하거나, 스펙 파일로 클라이언트 코드를 자동 생성할 수 있습니다.

Swagger UI

브라우저에서 API를 바로 테스트

열기

OpenAPI 스펙

엔드포인트, 파라미터, 응답 정의

Postman Import

Import → Link에 스펙 URL 입력

https://api.fidox.co/openapi.json

Swagger UI 사용법

  1. https://api.fidox.co/docs 접속
  2. 우측 상단 Authorize 클릭
  3. 발급받은 토큰 입력 (Bearer 없이 토큰만)
  4. API 선택 → Try it out → Execute

클라이언트 코드 자동 생성

openapi-generator로 원하는 언어의 API 클라이언트를 자동 생성할 수 있습니다.

curl
curl -o openapi.json https://api.fidox.co/openapi.json
npx
# Python
npx @openapitools/openapi-generator-cli generate \
  -i openapi.json -g python -o ./fidox-python

# TypeScript
npx @openapitools/openapi-generator-cli generate \
  -i openapi.json -g typescript-fetch -o ./fidox-ts

도움이 필요하신가요?

API 연동 중 문제가 발생하면 기술 지원팀에 문의해주세요.

기술 지원 문의