> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# 사용자 얼굴 업로드 API: 벤더 사용자 프로필
> vendor_data로 사용자를 생성하거나 가져온 후, Didit의 기존 사용자 프로필에 base64 얼굴 이미지를 업로드합니다.
사용자 얼굴 업로드 프롬프트
프롬프트를 클립보드에 복사
\
\`Goal: Attach a trusted imported face image to an existing Didit User profile.
Use case: I am migrating users from another provider. I already have a stable vendor_data and a face image I am allowed to process. I want the User profile to carry that face for evidence, duplicate detection, and face search.
Flow:
1\. Create or retrieve the User by vendor_data:
POST https://verification.didit.me/v3/users/create/
GET https://verification.didit.me/v3/users/{vendor_data}/
2\. Read didit_internal_id from the User response.
3\. Upload the face to:
POST https://verification.didit.me/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/
Auth: x-api-key for the same application.
Content-Type: application/json
Request body:
\- image (string, required) — raw base64-encoded JPG or PNG. Do not include a data URL prefix. Max decoded size: 2 MB.
\- comment (string, optional) — operator-visible note, for example "Imported from previous KYC provider".
Response 201:
\{
"uuid": "face-upload-uuid",
"image_url": "https://signed-url.example/...",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}
Limits:
\- Max 5 manually uploaded faces per User.
\- The image must decode as an image and contain a detectable face.
\- This enrolls the face for profile evidence and matching. It does not add the face to a blocklist.
To block a face, use POST /v3/lists/{list_uuid}/entries/face-upload/ with a face-type list instead.`
\
붙여넣을 곳
## 개요다른 제공업체에서 사용자를 가져오고 각 사용자의 신뢰할 수 있는 얼굴 이미지가 이미 있는 경우 이 endpoint를 사용합니다. 사용자는 계속 `vendor_data`로 식별되지만, 이 프로필 첨부 endpoint는 대상 사용자를 명확히 하기 위해 `didit_internal_id`를 사용합니다.> [!NOTE]
>
> 이것은 [목록에 얼굴 업로드](https://docs.didit.me/ko/management-api/lists/upload-face.md)와 다릅니다. 프로필 업로드는 증거, 중복 감지, 얼굴 검색을 위해 얼굴을 사용자에게 첨부합니다. 목록 업로드는 얼굴을 얼굴 유형 차단 목록에 추가하여 이후 일치 세션을 거부할 수 있도록 합니다.## endpoint**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**## 마이그레이션 흐름**1. 사용자 생성 또는 찾기**새 프로필을 만들려면 [`POST /v3/users/create/`](https://docs.didit.me/ko/management-api/users/create)를 호출하고, 기존 프로필은 [`GET /v3/users/{vendor_data}/`](https://docs.didit.me/ko/management-api/users/get)를 호출합니다.**2. didit\_internal\_id 저장**사용자 응답에는 `didit_internal_id`가 포함됩니다. 데이터베이스에서는 계속 `vendor_data`를 사용하고, `didit_internal_id`는 프로필 첨부 endpoint에서만 사용합니다.**3. 얼굴 업로드**`image` 필드에 원시 base64 이미지를 전송합니다. 백엔드는 저장하기 전에 이미지 디코딩, 이미지 크기, 얼굴 감지를 검증합니다.## 예제```bash theme={null}
# 1. Create the User keyed by your external id
curl -X POST https://verification.didit.me/v3/users/create/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vendor_data": "user-42",
"display_name": "Jane Doe",
"metadata": { "previous_provider": "legacy-kyc-vendor" }
}'
# 2. Upload an imported face to the returned didit_internal_id
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image": "",
"comment": "Imported from previous KYC provider"
}'
```## 요청 본문| 필드 | 유형 | 필수 | 설명 |
| - | - | - | - |
| `image` | 문자열 | 예 | 원시 base64로 인코딩된 JPG 또는 PNG. `data:image/...;base64,`를 포함하지 마십시오. 디코딩 후 최대 크기: 2 MB. |
| `comment` | 문자열 | 아니요 | 사용자 프로필에 표시되는 운영자용 메모. |## 응답```json theme={null}
{
"uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"image_url": "https://signed-url.example/face.jpg",
"comment": "Imported from previous KYC provider",
"uploaded_by": "api",
"created_at": "2026-05-18T12:00:00Z"
}
```## 검증 및 제한- 사용자당 수동으로 업로드한 얼굴은 최대 5개입니다.
- 디코딩 후 이미지의 최대 크기는 2 MB입니다.
- 이미지는 유효한 base64여야 하며 이미지로 디코딩되어야 합니다.
- 이미지에는 감지 가능한 얼굴이 있어야 합니다. 가능하면 정면이고 조명이 좋은 얼굴 크롭을 사용하십시오.
- 업로드된 얼굴은 이후 중복 감지와 얼굴 검색을 위해 색인됩니다.
- 업로드된 얼굴은 자동으로 차단 목록에 추가되지 않습니다.## 얼굴 목록 조회 또는 삭제프로필 얼굴 목록 조회:```bash theme={null}
curl https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/ \
-H "x-api-key: YOUR_API_KEY"
```프로필 얼굴 한 개 삭제:```bash theme={null}
curl -X DELETE https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/$FACE_UUID/ \
-H "x-api-key: YOUR_API_KEY"
```## 권한같은 애플리케이션의 API 키를 사용합니다. 해당 키는 대상 사용자 프로필을 관리할 수 있도록 허용된 앱에 속해 있어야 합니다.## 실패 상황- `400`: 잘못된 base64, 잘못된 이미지, 감지 가능한 얼굴 없음, 2 MB를 초과하는 이미지, 또는 사용자에게 이미 업로드된 얼굴이 5개 있는 경우.
- `401`: 자격 증명이 없거나 유효하지 않음.
- `403`: API 키는 유효하지만 이 사용자 프로필을 관리할 권한이 없음.
- `404`: 애플리케이션에 해당 `didit_internal_id`를 가진 사용자가 없음.
- `429`: 속도 제한에 걸림. `Retry-After`를 사용하여 재시도 전에 대기하십시오.## 관련 문서- [사용자 생성](https://docs.didit.me/ko/management-api/users/create.md)
- [사용자 조회](https://docs.didit.me/ko/management-api/users/get.md)
- [사용자 가져오기 및 내보내기](https://docs.didit.me/ko/entities/users/import-export.md)
- [얼굴 및 생체 인식](https://docs.didit.me/ko/entities/users/faces-and-biometrics.md)
- [차단 목록에 얼굴 업로드](https://docs.didit.me/ko/management-api/lists/upload-face.md)
## OpenAPI
````yaml ko/openapi-25.json POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: 신분증 인증 API입니다. x-api-key 헤더로 인증합니다.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/:
post:
tags:
- Users
summary: 사용자 얼굴 업로드
description: >-
신뢰할 수 있는 가져온 얼굴 이미지를 기존 사용자 프로필에 첨부합니다. `vendor_data`로 사용자를 생성하거나 조회한 후
해당 `didit_internal_id`를 확인하여 이 기능을 사용하십시오. 업로드된 얼굴은 사용자 프로필에 저장되며 중복 감지
및 얼굴 검색을 위해 색인화됩니다. 얼굴 차단 목록에는 추가되지 않습니다.
operationId: upload_user_face
parameters:
- name: organization_id
in: path
required: true
schema:
type: string
format: uuid
description: 애플리케이션을 소유한 조직 UUID입니다.
- name: application_id
in: path
required: true
schema:
type: string
format: uuid
description: 사용자 프로필을 소유한 애플리케이션 UUID입니다.
- name: didit_internal_id
in: path
required: true
schema:
type: string
format: uuid
description: >-
`GET /v3/users/{vendor_data}/` 및 `POST /v3/users/create/`에서
`didit_internal_id`로 반환되는 Didit 내부 사용자 UUID입니다.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- image
properties:
image:
type: string
format: byte
description: >-
원시 base64 인코딩된 JPG 또는 PNG 얼굴 이미지입니다.
`data:image/...;base64,` 접두사를 포함하지 마세요. 디코딩된 최대 크기: 2 MB.
comment:
type: string
description: 업로드된 얼굴에 대해 운영자에게 표시되는 선택적 메모입니다.
default: ''
examples:
Imported face:
summary: 이전 공급업체에서 가져온 얼굴을 첨부합니다
value:
image: /9j/4AAQSkZJRgABAQEA...
comment: Imported from previous KYC provider
responses:
'201':
description: 얼굴이 업로드되어 사용자 프로필에 첨부되었습니다.
content:
application/json:
schema:
type: object
required:
- uuid
- image_url
- comment
- uploaded_by
- created_at
properties:
uuid:
type: string
format: uuid
description: 업로드된 사용자 얼굴 레코드의 UUID입니다.
image_url:
type: string
format: uri
nullable: true
description: 업로드된 얼굴 이미지의 서명된 URL입니다.
comment:
type: string
nullable: true
description: 얼굴을 업로드할 때 제공된 코멘트입니다.
uploaded_by:
type: string
nullable: true
description: 가능한 경우 업로더의 이메일 또는 행위자 식별자입니다.
created_at:
type: string
format: date-time
description: 업로드 타임스탬프입니다.
examples:
Uploaded:
value:
uuid: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
image_url: https://signed-url.example/face.jpg
comment: Imported from previous KYC provider
uploaded_by: api
created_at: '2026-05-18T12:00:00Z'
'400':
description: >-
유효하지 않은 요청 본문 또는 이미지입니다. 일반적인 원인: 유효하지 않은 base64, 유효하지 않은 이미지, 감지
가능한 얼굴 없음, 2 MB 초과 이미지, 임베딩 누락, 또는 사용자가 이미 5개의 업로드된 얼굴을 보유한 경우입니다.
content:
application/json:
examples:
No face:
value:
image: >-
No face detected in the image. Please upload a clear photo
with a visible face.
Too many faces:
value:
detail: Maximum of 5 faces per user reached.
Too large:
value:
image: Image exceeds maximum size of 2 MB.
'401':
description: API 키가 누락되었거나 유효하지 않습니다.
content:
application/json:
examples:
Missing key:
value:
detail: Authentication credentials were not provided.
'403':
description: 자격 증명이 유효하지만 이 애플리케이션의 사용자 프로필을 작성할 수 없습니다.
content:
application/json:
examples:
Forbidden:
value:
detail: You do not have permission to perform this action.
'404':
description: 애플리케이션에 해당 `didit_internal_id`를 가진 사용자가 존재하지 않습니다.
content:
application/json:
examples:
Not found:
value:
detail: Not found.
'429':
description: 속도 제한 초과. 대기 후 재시도하세요.
content:
application/json:
examples:
Rate limited:
value:
detail: Request was throttled. Expected available in 30 seconds.
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: curl
label: curl
source: >-
curl -X POST
'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/'
\
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider"}'
- lang: python
label: Python
source: |-
from didit import Didit
# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
# and DIDIT_APPLICATION_ID.
client = Didit()
result = client.users.upload_face(
"11111111-2222-3333-4444-555555555555",
image="/9j/4AAQSkZJRgABAQEA...",
comment="Imported from previous KYC provider",
)
print(result)
- lang: javascript
label: Node.js
source: >-
import Didit from "@didit-protocol/sdk-node";
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
const didit = new Didit();
const result = await
didit.users.uploadFace("11111111-2222-3333-4444-555555555555", {
image: "/9j/4AAQSkZJRgABAQEA...",
comment: "Imported from previous KYC provider",
});
console.log(result);
- lang: go
label: Go
source: "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.UsersUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQEA...\",\n\tComment: didit.String(\"Imported from previous KYC provider\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
- lang: java
label: Java
source: >-
import me.didit.Didit;
import me.didit.types.UsersUploadFaceParams;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
Didit client = new Didit();
var result =
client.users().uploadFace("11111111-2222-3333-4444-555555555555",
UsersUploadFaceParams.builder()
.image("/9j/4AAQSkZJRgABAQEA...")
.comment("Imported from previous KYC provider")
.build());
System.out.println(result);
- lang: php
label: PHP
source: >-
users->uploadFace('11111111-2222-3333-4444-555555555555', [
'image' => '/9j/4AAQSkZJRgABAQEA...',
'comment' => 'Imported from previous KYC provider',
]);
print_r($result->toArray());
- lang: ruby
label: Ruby
source: |-
require "didit"
# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
# and DIDIT_APPLICATION_ID.
didit = Didit::Client.new
result = didit.users.upload_face(
"11111111-2222-3333-4444-555555555555",
image: "/9j/4AAQSkZJRgABAQEA...",
comment: "Imported from previous KYC provider"
)
puts result.to_h
- lang: csharp
label: .NET
source: >-
using System;
using System.Text.Json;
using Didit;
// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID
// and DIDIT_APPLICATION_ID.
using var client = new DiditClient();
var result = await
client.Users.UploadFaceAsync("11111111-2222-3333-4444-555555555555",
new UsersUploadFaceParams
{
Image = "/9j/4AAQSkZJRgABAQEA...",
Comment = "Imported from previous KYC provider",
});
Console.WriteLine(JsonSerializer.Serialize(result));
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
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 를 참고하십시오.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.