메인 콘텐츠로 건너뛰기
POST
cURL

인증

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 를 참고하십시오.

본문

multipart/form-data
user_image
file
필수

검색할 정면 얼굴 이미지입니다. 허용되는 확장자: tiff, jpg, jpeg, png, webp. 최대 업로드 크기: 5 MB(더 큰 파일은 400 오류로 거부됨). 이미지는 처리 전에 자동으로 ~0.5 MB로 압축되므로 매우 높은 해상도라고 해서 정확도가 향상되지는 않습니다. 이미지에는 감지 가능한 얼굴이 하나 이상 포함되어야 하며, 그렇지 않으면 endpoint에서 400을 반환합니다. 여러 얼굴이 있는 경우 가장 큰 얼굴이 검색되며 MULTIPLE_FACES_DETECTED 경고가 추가됩니다.

search_type
enum<string>
기본값:most_similar

검색 정책. most_similar(기본값)는 애플리케이션에 등록된 모든 얼굴의 유사도 순위를 매깁니다. blocklisted_or_approved는 차단 목록에 등록된 얼굴, 허용 목록에 등록된 얼굴, 승인된 세션의 얼굴, 가져온 사용자 프로필 얼굴로 후보를 제한하며, 차단 목록 항목이 먼저 정렬됩니다.

사용 가능한 옵션:
most_similar,
blocklisted_or_approved
예시:

"most_similar"

rotate_image
boolean
기본값:false

true인 경우 서비스가 입력을 90도씩 회전해 보고 최적의 얼굴 감지 결과를 제공하는 방향을 사용합니다. EXIF 방향 정보가 누락되었을 때 유용합니다. 지연 시간이 증가합니다.

예시:

false

save_api_request
boolean
기본값:true

true(기본값)인 경우 호출을 API 유형의 세션으로 저장하고, status.updated webhook을 발행하며, match_image_url 값을 사전 서명하고, 검색된 얼굴을 얼굴 검색 인덱스에 등록합니다(얼굴 검색 등록 건은 향후 검색 대상에서 제외됨). false인 경우 검색은 단발성으로 처리되어 세션이 저장되지 않고 얼굴도 등록되지 않습니다.

예시:

true

vendor_data
string

저장된 세션에 저장되고 다시 반환되는 선택적 불투명 식별자(사용자 ID, 이메일, UUID 등)입니다. 검색 결과에서 동일 사용자의 얼굴을 제외하지는 않습니다.

예시:

"user-123"

metadata
object

세션과 함께 저장되고(save_api_request=true인 경우) 그대로 반환되는 선택적 JSON 객체입니다. multipart 요청에서는 JSON 인코딩된 문자열 필드로 전송하십시오. 객체로 파싱됩니다.

예시:

응답

얼굴 검색이 완료되었습니다. face_search.matches는 유사도 순으로 정렬된 유사한 얼굴을 최대 5개까지 포함합니다. 빈 배열은 등록된 얼굴 중 유사도 하한을 초과한 얼굴이 없음을 의미합니다. status는 차단 목록에 일치하는 경우에만 Declined입니다. 중복 일치만으로는 Approved를 반환하므로 status뿐만 아니라 matches 및 warnings를 확인하십시오. save_api_request=true인 경우, request_id는 저장된 세션 ID입니다. 각 일치 항목에는 source(session, imported, list_entry 또는 retained_template), vendor_user_id, biometric_template_id가 포함됩니다. retained_template 일치는 소스 세션이 삭제된 후 보관된 이미지가 없는 생체 인식 템플릿에서 비롯되며, 이 일치 항목의 세션 필드, match_image_url, user_details는 null입니다.

request_id
string<uuid>

save_api_request=true일 때 유지된 세션 ID(GET /v3/session/{sessionId}/decision/와 함께 사용 가능), 그렇지 않으면 임시 상관관계 UUID입니다.

vendor_data
string | null

전송한 vendor_data의 에코 값 또는 null입니다.

metadata
object | null

전송한 metadata 객체의 에코 값 또는 null입니다.

created_at
string<date-time>

응답이 생성된 시점의 ISO 8601 타임스탬프(UTC)(예: 2026-06-12T01:04:42.763237+00:00)입니다.

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