메인 콘텐츠로 건너뛰기
POST
curl
base64로 인코딩된 얼굴 이미지를 얼굴 차단 목록 또는 허용 목록에 업로드합니다. Didit는 이미지에서 얼굴을 감지하고 가장 큰 얼굴 하나를 남긴 뒤, 이미지와 해당 얼굴을 자른 이미지를 저장하고, 이후 새 세션과 비교할 생체 인식 템플릿을 계산합니다. 새 항목의 value는 해당 얼굴의 UUID입니다. entry_type: face이고 list_type: blocklist 또는 list_type: allowlist인 목록에서만 사용할 수 있습니다.
기존 세션의 얼굴을 차단 목록이나 허용 목록에 추가하려면 reference_session_id를 사용하는 항목 생성을 대신 사용하세요. 이 경우 항목이 해당 세션에 연결됩니다.
이미지에는 명확하게 보이는 얼굴이 있어야 하며, 디코딩 후 크기는 최대 2 MB여야 합니다. 얼굴이 감지되지 않으면 요청은 400을 반환하고 항목은 생성되지 않습니다. 얼굴 분석을 일시적으로 사용할 수 없으면 503을 반환하므로 나중에 다시 시도하세요.
얼굴을 목록에서 제거하려면 해당 항목을 삭제하세요. 삭제하면 새 세션과 더 이상 일치하지 않습니다.

인증

x-api-key
string
header
필수

Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오.

경로 매개변수

list_uuid
string<uuid>
필수

entry_type: face 및 list_type: blocklist 또는 allowlist인 목록의 UUID입니다.

본문

application/json
image
string<byte>
필수

디코딩 시 최대 2MB 크기의 얼굴이 선명하게 보이는 Base64 인코딩된 JPEG 또는 PNG입니다. data:image/...;base64, 접두사 없이 순수 Base64 문자열만 전송해야 합니다.

comment
string
기본값:""

목록 등록 사유 등과 같은 선택적 자유 텍스트 메모입니다.

응답

얼굴 항목이 생성되었습니다.

목록 내의 값 1개입니다.

uuid
string<uuid>
필수

항목 식별자. 목록 항목 삭제에서 entry_uuid로 사용합니다.

value
string
필수

목록에 등록된 값: E.164 형식의 전화번호, 이메일 주소, 문서 번호, IP 주소 또는 CIDR 범위, 기기 지문, 지갑 주소, 은행 계좌, ISO 3166-1 alpha-3 국가 코드, vendor_data, key 목록의 모든 문자열, 또는 얼굴 목록에 저장된 얼굴의 UUID입니다. 전송하는 값은 전화번호와 국가 코드를 제외하고 소문자로 저장됩니다. 일치 여부 확인 시 대소문자를 구분하지 않습니다.

display_label
string | null
필수

사람이 읽기 쉬운 라벨입니다. 아무것도 전송하지 않으면 Didit이 세션에서 가져온 항목(예: 소지자의 성명 및 문서 번호)으로 채웁니다.

Maximum string length: 512
comment
string
필수

자유 형식 메모입니다. 설정되지 않은 경우 빈 문자열입니다.

added_by
string | null
필수

항목을 추가한 주체: api(API 키), 콘솔 사용자의 이메일 주소 또는 console, system 또는 migration(Didit이 생성한 항목), 또는 rule(거래 규칙 또는 모니터링 규칙의 작업).

reference_session_id
string<uuid> | null
필수

해당 항목을 가져온 인증 세션입니다. 항목이 값으로 직접 추가된 경우 null입니다.

reference_session_number
integer | null
필수

콘솔에 표시되는 해당 세션의 애플리케이션별 번호입니다.

reference_session_type
enum<string> | null
필수

개인 인증 세션인 경우 kyc, 기업 확인 세션인 경우 kyb, 세션이 없는 경우 null입니다.

사용 가능한 옵션:
kyc,
kyb,
null
reference_object_uuid
string<uuid> | null
필수

항목이 나타내는 레코드입니다. 세션에서 읽은 얼굴, 문서, 전화번호 또는 이메일 레코드, 목록에 얼굴 업로드를 통해 생성된 얼굴, 또는 전송한 UUID(예: 거래 UUID 또는 사용자의 didit_internal_id)입니다.

metadata
object | null
필수

추가 컨텍스트입니다. 항목 생성 시 전송한 metadata와 병합된 Didit이 설정한 키(여기에 나열됨)가 포함되며, 저장된 그대로 반환됩니다. 없는 경우 null입니다.

created_at
string<date-time>
필수

항목이 추가된 시점입니다.

마지막 수정일 2026년 11월 7일