Guard — 개인정보 탐지·마스킹
텍스트에 개인정보가 들어 있는지 검사하고, 필요하면 가려서 돌려주는 엔드포인트입니다.
로그를 저장하기 전에, 사용자 입력을 외부 모델에 넘기기 전에, 상담 기록을 분석에 쓰기 전에 한 번 통과시키는 용도입니다. 조직의 콘텐츠 필터 설정과는 별개로 동작합니다 — 이 호출은 "이 텍스트를 검사해 달라"는 명시적인 요청이기 때문입니다.
엔드포인트
| Method | Path | 설명 |
|---|---|---|
| POST | /v1/gateway/guard/ | 개인정보 탐지 또는 마스킹 |
텍스트 전용입니다. 이미지를 넣으면
400으로 거절합니다. 이미지 검사는 문서 변환 설비를 함께 쓰기 때문에 현재 API로 열려 있지 않습니다.파라미터
input
검사할 텍스트. 문자열 하나 또는 문자열 배열을 받습니다. 최대 100개, 항목당 최대 20,000자입니다. 배열 순서는 응답의 string | array
required
index로 보존됩니다.mode
string
mask(기본값) 또는 detect.mask— 무엇을 찾았는지 알려 주고, 가린 문장(masked_text)도 함께 돌려줍니다.detect— 찾은 것만 알려 줍니다.masked_text는 오지 않습니다.
categories
검사할 항목 (기본값: 전체). 아래 8가지 중에서 고릅니다.array
| 값 | 대상 |
|---|---|
phone | 전화번호 |
email | 이메일 주소 |
national_id | 주민등록번호 |
credit_card | 카드번호 |
passport | 여권번호 |
driver_license | 운전면허번호 |
vehicle_plate | 차량번호 |
date_of_birth | 생년월일 |
목록에 없는 값을 보내면
400과 함께 쓸 수 있는 값을 안내합니다.요청
응답
최상위
flagged는 항목 중 하나라도 걸리면 true입니다. 배치 전체를 한 번에 판정할 때 쓰면 편합니다.검사는 2단계입니다
- 탐지 — 마스킹 모델이 후보 구간을 찾습니다.
- 검증 — 검증 모델이 각 후보가 정말 실제 개인정보인지 다시 판단하고, 아닌 것은 되살립니다.
2단계가 있기 때문에 예제·샘플 데이터는 걸리지 않습니다. 실제로 확인된 동작입니다.
| 입력 | 결과 | 이유 |
|---|---|---|
hong@example.com | 탐지 안 됨 | example.com은 문서용으로 예약된 도메인입니다 |
minsu.kim@samsung.com | email 탐지 | 실제 도메인입니다 |
4111-1111-1111-1111 | 탐지 안 됨 | 널리 알려진 테스트 카드번호입니다 |
5312 7788 4410 9023 | credit_card 탐지 | 실제 형식의 번호입니다 |
즉 "아무것도 안 나왔다"가 곧 "형식이 안 맞았다"는 뜻은 아닙니다. 검증 단계가 일부러 되살린 경우가 있습니다.
과금
항목 1개당 1건으로 계산합니다. 글자 수와 무관하므로, 짧은 문장 100개를 보내면 100건이고 긴 문서 1개를 보내면 1건입니다.
긴 텍스트를 잘게 쪼개서 보내면 그만큼 비용이 늘어납니다. 문단 단위로 묶어서 보내는 편이 유리합니다.
알아 두면 좋은 것
- 이 엔드포인트는
model파라미터가 없습니다. 검사 모델은 고정입니다. - 요청 본문은 저장하지 않습니다. 사용 내역에는 호출이 있었다는 사실과 건수만 남습니다.
- 이름·주소는 검사 대상이 아닙니다. 위 표의 8가지가 전부입니다.
마지막 수정 날짜: Sep 18, 2026