Bulk Register
벌크 얼굴 등록
ZIP 한 번으로 수십~수만 명의 얼굴을 한꺼번에 등록합니다. 임직원 마이그레이션, 고객 사전 등록 등에 사용하세요.
언제 쓰나요?
- 기존 시스템의 회원 사진을 FIDOX로 일괄 이관할 때
- 출입통제/근태 도입 시 직원 사진을 한 번에 등록할 때
- 이벤트/방문객 사전 등록을 단체로 처리할 때
일반 API
POST /face/register는 단건 호출용입니다. 다수를 빠르게 처리할 땐 벌크 등록을 사용하세요 — fr-core 부하 보호(자체 RPS 제한)와 진행 상황 추적이 함께 제공됩니다.ZIP 파일 구조
최상위에 items.json 한 개 + 이미지 파일들. 콘솔에서 이미지를 드래그하면 자동으로 묶여 만들어집니다.
input.zip
├── items.json # 필수 (배열)
├── kim.jpg
├── lee.jpg
└── ...items.json 예시
[
{ "userCode": "EMP-001", "imageName": "kim.jpg", "name": "김철수" },
{ "userCode": "EMP-002", "imageName": "lee.jpg", "name": "이영희",
"metadata": { "dept": "개발팀" } }
]| 옵션 | 타입 | 설명 |
|---|---|---|
| userCode | string | 고객사 내 고유 코드 (필수). 영문/숫자/`_`/`.`/`-` 사용 가능, 64자 이내 |
| imageName | string | ZIP 안의 이미지 파일명 (필수) |
| name | string | 이름 (선택, 미입력 시 userCode 사용) |
| metadata | object | 자유 키–값 쌍 (선택). 추후 채널 통계/필터에 활용 |
업로드하기
1
콘솔 → 채널 선택 → 사이드바 '벌크 등록'
2
모드 선택
- ZIP 파일 이미 만들어둔 ZIP 업로드 — items.json 포함
- 이미지 여러 개 사진 파일 다중 선택 → 콘솔이 파일명 규칙(
{userCode}_{name}.jpg)에서 items.json을 자동 생성
3
업로드 → 진행
내부적으로 4단계: 이미지 묶는 중 → 잡 준비 중 → 업로드 중 N% → 검증 중. 큰 파일도 브라우저가 직접 S3에 업로드하므로 1GB ZIP도 안정적입니다.
4
잡 목록에서 진행률 확인
상태가 대기 → 처리 중 → 완료로 갱신됩니다. 5초마다 자동 새로고침.
파일명에서 자동 추출을 쓸 때는 한글이나 공백을 피하고 영문/숫자 위주로 작성하세요. (예:
EMP-001_김철수.jpg)한도와 보호 정책
| 옵션 | 기본값 | 설명 |
|---|---|---|
| ZIP 크기 | 1024 MB | 한 잡당 ZIP 파일 최대 크기 |
| 이미지 크기 | 12 MB | 단일 이미지 최대 크기 |
| row 수 | 10,000 건 | 한 잡당 처리 가능한 사용자 수 |
| 처리 속도 | 2 RPS (메인) / 6 RPS (격리) | 실시간 verify 호출이 느려지지 않도록 자체 제한합니다 |
| presigned URL TTL | 15분 | 업로드 URL 유효 시간 (초과 시 다시 잡 생성) |
| 이미지 보관 | 잡 완료 직후 삭제 | ZIP은 처리 완료 시 자동으로 S3에서 제거됩니다 |
결과 확인과 실패 처리
잡 카드/상세에 성공/실패 건수가 표시됩니다. 실패가 있으면 errors.csv 다운로드 버튼이 노출됩니다.
errors.csv 컬럼
| 옵션 | 설명 |
|---|---|
| rowIndex | items.json 내 인덱스 (0부터) |
| userCode | 해당 row의 사용자 코드 |
| imageName | 이미지 파일명 |
| errorCode | 분류된 에러 코드 (아래 표 참조) |
| errorMessage | 서버가 반환한 원본 메시지 |
주요 errorCode
| 옵션 | 설명 |
|---|---|
| image-not-found | items.json의 imageName이 ZIP 안에 없음 |
| image-decode-fail | ZIP에서 이미지 추출 또는 디코드 실패 (파일 손상) |
| plan-limit-exceeded | 현재 플랜의 이용자 수 한도에 도달 — 플랜 변경 또는 미사용 사용자 정리 |
| duplicate-user | 같은 userCode가 이미 등록됨 (FR004) |
| duplicate-face | 동일한 얼굴이 다른 userCode로 이미 등록됨 (FR008) |
| face-not-detected | 이미지에서 얼굴을 찾지 못함 — 정면, 충분한 해상도 권장 |
| fr-engine-error | FR 엔진 처리 중 일시 오류 — 일정 시간 후 재시도 권장 |
errors.csv는 UTF-8 BOM 포함이라 Excel에서 바로 열어도 한글이 깨지지 않습니다.
API로 직접 호출
서버 to 서버 자동화가 필요하면 Member JWT로 다음 3단계를 호출합니다 (콘솔 UI가 내부적으로 쓰는 흐름과 동일).
# 1) init — presigned PUT URL 발급
POST /v1/channels/:channelId/bulk-register/init
→ { jobId, uploadUrl, uploadExpiresInSec: 900, maxZipMb }
# 2) PUT — 브라우저/서버가 S3에 ZIP 그대로 PUT
PUT <uploadUrl>
Content-Type: application/zip
# 3) complete — 검증 + 큐 enqueue
POST /v1/channels/:channelId/bulk-register/:jobId/complete
→ { id, status: "queued", totalRows, isolate }
# 잡 상태/결과 조회 (errors.csv URL 포함)
GET /v1/channels/:channelId/bulk-register/:jobId서버 to 서버에서도 presigned PUT TTL 15분 안에 PUT을 마쳐야 합니다. 큰 파일은 multipart 업로드를 자동 지원하는 SDK(boto3, AWS SDK 등)를 사용하세요.
자주 발생하는 문제
| 옵션 | 설명 |
|---|---|
| "CORS 차단" 알림 | 브라우저 origin이 화이트리스트에 없음 — 콘솔이 아닌 다른 도메인에서 PUT 시 발생. 콘솔에서 업로드하거나 서버 사이드에서 호출 |
| 잡이 계속 대기 상태 | 워커가 일시 정지일 수 있음 — 운영팀 문의 |
| 실패율이 비정상적으로 높음 | 대부분 image-not-found(파일명 불일치) 또는 plan-limit. errors.csv 첫 몇 줄로 패턴 확인 |
| 같은 사람을 재등록하고 싶음 | 먼저 기존 사용자를 삭제 후 다시 등록 (channel 설정에 따라 duplicate-face 감지가 막을 수 있음) |