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

개요

다른 제공업체에서 사용자를 가져오고 각 사용자의 신뢰할 수 있는 얼굴 이미지가 이미 있는 경우 이 endpoint를 사용합니다. 사용자는 계속 vendor_data로 식별되지만, 이 프로필 첨부 endpoint는 대상 사용자를 명확히 하기 위해 didit_internal_id를 사용합니다.
이것은 목록에 얼굴 업로드와 다릅니다. 프로필 업로드는 증거, 중복 감지, 얼굴 검색을 위해 얼굴을 사용자에게 첨부합니다. 목록 업로드는 얼굴을 얼굴 유형 차단 목록에 추가하여 이후 일치 세션을 거부할 수 있도록 합니다.

endpoint

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/

마이그레이션 흐름

1

사용자 생성 또는 찾기

새 프로필을 만들려면 POST /v3/users/create/를 호출하고, 기존 프로필은 GET /v3/users/{vendor_data}/를 호출합니다.
2

didit_internal_id 저장

사용자 응답에는 didit_internal_id가 포함됩니다. 데이터베이스에서는 계속 vendor_data를 사용하고, didit_internal_id는 프로필 첨부 endpoint에서만 사용합니다.
3

얼굴 업로드

image 필드에 원시 base64 이미지를 전송합니다. 백엔드는 저장하기 전에 이미지 디코딩, 이미지 크기, 얼굴 감지를 검증합니다.

예제

요청 본문

응답

검증 및 제한

  • 사용자당 수동으로 업로드한 얼굴은 최대 5개입니다.
  • 디코딩 후 이미지의 최대 크기는 2 MB입니다.
  • 이미지는 유효한 base64여야 하며 이미지로 디코딩되어야 합니다.
  • 이미지에는 감지 가능한 얼굴이 있어야 합니다. 가능하면 정면이고 조명이 좋은 얼굴 크롭을 사용하십시오.
  • 업로드된 얼굴은 이후 중복 감지와 얼굴 검색을 위해 색인됩니다.
  • 업로드된 얼굴은 자동으로 차단 목록에 추가되지 않습니다.

얼굴 목록 조회 또는 삭제

프로필 얼굴 목록 조회:
프로필 얼굴 한 개 삭제:

권한

같은 애플리케이션의 API 키를 사용합니다. 해당 키는 대상 사용자 프로필을 관리할 수 있도록 허용된 앱에 속해 있어야 합니다.

실패 상황

  • 400: 잘못된 base64, 잘못된 이미지, 감지 가능한 얼굴 없음, 2 MB를 초과하는 이미지, 또는 사용자에게 이미 업로드된 얼굴이 5개 있는 경우.
  • 401: 자격 증명이 없거나 유효하지 않음.
  • 403: API 키는 유효하지만 이 사용자 프로필을 관리할 권한이 없음.
  • 404: 애플리케이션에 해당 didit_internal_id를 가진 사용자가 없음.
  • 429: 속도 제한에 걸림. Retry-After를 사용하여 재시도 전에 대기하십시오.

관련 문서

인증

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

경로 매개변수

organization_id
string<uuid>
필수

애플리케이션을 소유한 조직 UUID입니다.

application_id
string<uuid>
필수

사용자 프로필을 소유한 애플리케이션 UUID입니다.

didit_internal_id
string<uuid>
필수

GET /v3/users/{vendor_data}/ 및 POST /v3/users/create/에서 didit_internal_id로 반환되는 Didit 내부 사용자 UUID입니다.

본문

application/json
image
string<byte>
필수

원시 base64 인코딩된 JPG 또는 PNG 얼굴 이미지입니다. data:image/...;base64, 접두사를 포함하지 마세요. 디코딩된 최대 크기: 2 MB.

comment
string
기본값:""

업로드된 얼굴에 대해 운영자에게 표시되는 선택적 메모입니다.

응답

얼굴이 업로드되어 사용자 프로필에 첨부되었습니다.

uuid
string<uuid>
필수

업로드된 사용자 얼굴 레코드의 UUID입니다.

image_url
string<uri> | null
필수

업로드된 얼굴 이미지의 서명된 URL입니다.

comment
string | null
필수

얼굴을 업로드할 때 제공된 코멘트입니다.

uploaded_by
string | null
필수

가능한 경우 업로더의 이메일 또는 행위자 식별자입니다.

created_at
string<date-time>
필수

업로드 타임스탬프입니다.

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