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"
}

연동 흐름

API 키 발급

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

토큰 발급

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

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`필수	사용자 고유 코드 (사번, 회원ID 등)
`image`필수	얼굴 사진 (Base64)
`name`	사용자 이름 (선택)

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— 얼굴 인증 (1:1)

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

파라미터	설명
`userCode`필수	확인할 사용자 코드
`image`필수	현재 얼굴 사진 (Base64)
`context`	login \| monitoring \| general
`withLiveness`	true 시 실제 사람인지 검사 (사진 공격 방지)

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— 얼굴 식별 (1:N)

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

파라미터	설명
`image`필수	얼굴 사진 (Base64)
`withLiveness`	liveness 검증 포함 (기본 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`	이미지 품질 부족
`AUTH001`	인증 실패
`LIMIT001`	API 호출 한도 초과

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 사용법

https://api.fidox.co/docs 접속
우측 상단 Authorize 클릭
발급받은 토큰 입력 (Bearer 없이 토큰만)
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 연동 중 문제가 발생하면 기술 지원팀에 문의해주세요.

기술 지원 문의