> ## 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: 딥페이크 감지 > Didit의 패시브 라이브니스 API는 단일 이미지로 마스크, 인쇄물, 재생, 딥페이크를 감지합니다. 완전 패시브 방식, 2초 미만 추론, 사용량 기반 요금, 월 최소 요금 없음. ## OpenAPI ````yaml ko/openapi-25.json POST /v3/passive-liveness/ 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/passive-liveness/: post: tags: - Standalone APIs summary: 패시브 라이브니스 description: >- 단일 얼굴 이미지에서 인쇄된 사진, 화면 재생, 가면, 딥페이크와 같은 프레젠테이션 공격을 감지합니다. 비디오, 움직임 또는 사용자 상호작용이 필요하지 않습니다. **작동 방식.** 이미지는 생체 인식 모델에 의해 분석되며, 감지된 가장 큰 얼굴을 평가하여 라이브니스 `score`(0~100)를 산출합니다. `error` 심각도 경고가 발생하면 `status`는 `Declined`가 됩니다: - `NO_FACE_DETECTED` — 라이브니스 모델이 얼굴을 찾지 못함, - `LOW_LIVENESS_SCORE` — 점수가 `face_liveness_score_decline_threshold`(기본값 `30`) 이하임, - `LIVENESS_FACE_ATTACK` — 모델이 프레젠테이션 공격을 감지함, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` — 얼굴이 얼굴 차단 목록의 항목과 일치함. `MULTIPLE_FACES_DETECTED`는 `warning` 심각도 신호이며(거부되지 않음), `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`는 동일한 얼굴이 이미 다른 승인된 세션에 나타났음을 나타내는 `information` 심각도 신호입니다(절대 거부되지 않음). `face_quality` 및 `face_luminance`(0~100, nullable)는 캡처 품질을 나타냅니다. **차단 목록 및 중복 스크리닝.** 감지된 얼굴을 애플리케이션의 얼굴 검색 색인과 대조하여 `save_api_request` 설정 여부와 관계없이 **모든** 호출에서 실행됩니다. 동일한 `vendor_data`를 가진 이전 얼굴은 전체 색인 검색에서 제외되므로, 동일한 사용자에 대해 라이브니스를 다시 실행해도 `DUPLICATED_FACE`가 발생하지 않으며 호출자의 자체 `vendor_data`가 포함된 세션에서 유래한 차단 목록 얼굴 또한 플래그가 지정되지 않습니다(동일한 `vendor_data` 얼굴에 대해서는 `FACE_IN_BLOCKLIST` 스크리닝이 건너뛰어짐). **결제.** 각 `200` 응답은 패시브 라이브니스 API 크레딧 1개를 소비합니다(요금제 크레딧 또는 충전 잔액에서 차감). 잔액이 부족하면 이미지 처리 전에 `403`이 반환됩니다. **세션 유지 및 얼굴 등록(`save_api_request`, 기본값 `true`).** `true`인 경우, 호출은 API 유형 세션(Business Console, 반환된 `request_id`를 통한 `GET /v3/session/{sessionId}/decision/`, `status.updated` webhook)으로 유지되고 기준 이미지와 얼굴 크롭이 저장되며, 감지된 얼굴이 **얼굴 검색 색인에 등록**되어 이후의 얼굴 검색 호출 및 중복 확인에서 일치 여부를 대조할 수 있습니다. `false`인 경우, 일회성 호출로 처리되어 아무것도 저장되지 않고 얼굴도 등록되지 않습니다(차단 목록/중복 스크리닝은 계속 실행됨). **샌드박스.** 샌드박스 API 키는 모든 처리 및 결제를 건너뜁니다. 요청 유효성 검사 후(형식이 잘못된 입력은 여전히 `400` 반환), endpoint는 정적 `Approved` 모의 payload를 반환하고, 세션은 유지되지 않으며, 크레딧도 소비되지 않습니다. **인증.** 애플리케이션의 API 키를 `x-api-key` 헤더로 전송하십시오. 인증 정보가 누락되거나 잘못된 경우 `403`(`{"detail": "You do not have permission to perform this action."}`)이 반환되며, 이 API는 절대로 `401`을 반환하지 않습니다. **속도 제한.** 모든 POST/PATCH/DELETE endpoint에 걸쳐 API 키당 분당 300회의 쓰기 예산이 공유되며, 이를 초과하면 `429`가 반환됩니다. operationId: post_v3passive-liveness parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- 정면 얼굴 이미지입니다(예: 셀피). 허용되는 확장자: `tiff`, `jpg`, `jpeg`, `png`, `webp`. 최대 업로드 크기: **5 MB**(더 큰 파일은 `400` 오류로 거부됨). 이미지는 처리 전에 자동으로 ~0.5 MB로 압축되므로 매우 높은 해상도라고 해서 정확도가 향상되지는 않습니다. 이미지에는 단일 대상만 포함되어야 합니다. 여러 얼굴이 있는 경우 가장 큰 얼굴이 평가되며 `MULTIPLE_FACES_DETECTED` 경고가 추가됩니다. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- 라이브니스 점수 임계값(0–100). 계산된 점수가 이 값 **이하**인 경우 `LOW_LIVENESS_SCORE` 경고를 생성하고 `status`를 `Declined`로 설정합니다. 기본값은 `30`입니다. 더 엄격한 안티 스푸핑 태세를 위해 값을 올리십시오. 0–100 범위를 벗어난 값은 `400`을 반환합니다. example: 30 rotate_image: type: boolean default: false description: >- `true`인 경우 서비스가 입력을 90도씩 회전해 보고 최적의 얼굴 감지 결과를 제공하는 방향을 사용합니다. EXIF 방향 정보가 누락되었을 때 유용합니다. 지연 시간이 증가합니다. example: false save_api_request: type: boolean default: true description: >- `true`(기본값)인 경우 호출을 API 유형의 세션으로 저장하고, 얼굴 이미지를 저장하며, `status.updated` webhook을 발행하고, 감지된 얼굴을 얼굴 검색 인덱스에 등록합니다. `false`인 경우 호출은 단발성으로 처리되어 아무것도 저장되지 않고 얼굴도 등록되지 않습니다. 차단 목록 및 중복 스크리닝은 어느 쪽이든 실행됩니다. example: true vendor_data: type: string description: >- 저장된 세션에 저장되고 다시 반환되는 선택적 불투명 식별자(사용자 ID, 이메일, UUID 등)입니다. 또한 동일한 `vendor_data`를 가진 이전 세션을 중복 얼굴 확인에서 제외하는 데 사용되므로, 동일한 사용자를 재인증할 때 `DUPLICATED_FACE`가 발생하지 않습니다. example: user-123 metadata: type: object additionalProperties: true description: >- 세션과 함께 저장되고(`save_api_request=true`인 경우) 그대로 반환되는 선택적 JSON 객체입니다. multipart 요청에서는 JSON 인코딩된 문자열 필드로 전송하십시오. 객체로 파싱됩니다. example: flow: withdrawal example: user_image: (binary JPEG/PNG selfie) face_liveness_score_decline_threshold: 30 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: withdrawal responses: '200': description: >- 패시브 라이브니스가 완료되었습니다. `liveness.score`는 이미지가 실제 사람인지에 대한 모델의 0–100 신뢰도 점수입니다. `error` 심각도 경고가 발생하지 않는 한 `status`는 `Approved`입니다. 스푸핑되었거나 차단 목록에 등록된 얼굴도 `200`을 반환하므로, HTTP 코드뿐만 아니라 `liveness.status`와 `liveness.warnings`를 확인해야 합니다. `save_api_request=true`인 경우, `request_id`는 저장된 세션 ID입니다. content: application/json: examples: Approved: summary: 실제 얼굴 — 경고 없음 value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef liveness: status: Approved method: PASSIVE score: 95 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 warnings: [] face_quality: 84.21 face_luminance: 50.33 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - presentation attack: summary: 모델이 스푸핑(인쇄물, 재생, 가면 등)을 감지했습니다. value: request_id: f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c liveness: status: Declined method: PASSIVE score: 12.5 user_image: entities: - bbox: - 100 - 120 - 420 - 540 confidence: 0.81 age: 30.1 gender: female race: null best_angle: 0 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. - risk: LIVENESS_FACE_ATTACK feature: LIVENESS additional_data: null log_type: error short_description: Liveness Face Attack long_description: >- The system detected a potential attempt to bypass the liveness check. face_quality: 72.4 face_luminance: 48.2 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - face on blocklist: summary: 실제 얼굴이지만 차단 목록 항목과 일치함 value: request_id: 0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e liveness: status: Declined method: PASSIVE score: 93.75 user_image: entities: - bbox: - 40 - 40 - 100 - 100 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 3242 api_service: null log_type: error short_description: Face in blocklist long_description: >- The system identified a face in the blocklist, which means the face is not allowed to be verified. face_quality: null face_luminance: null vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- `save_api_request=true`일 때 유지된 세션 ID(`GET /v3/session/{sessionId}/decision/`와 함께 사용 가능), 그렇지 않으면 임시 상관관계 UUID입니다. liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- 최소 하나 이상의 `error` 심각도 경고(얼굴 없음, 낮은 점수, 프레젠테이션 공격 또는 차단 목록 일치)가 발생한 경우 `Declined`, 그렇지 않은 경우 `Approved`. `warning`/`information` 항목(다중 얼굴, 중복)은 단독으로 거부되지 않습니다. method: type: string enum: - PASSIVE description: 이 endpoint의 경우 항상 `PASSIVE`입니다. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- 이미지가 스푸핑이 아닌 실제 인물을 묘사하고 있는지에 대한 라이브니스 신뢰도(0–100, 소수점 둘째 자리). 모델이 신뢰도를 반환하지 않은 경우 `null`입니다. example: 95 user_image: type: object description: 제출된 이미지에 대한 얼굴 감지 결과입니다. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- 처리된 이미지에서 `[x_min, y_min, x_max, y_max]` 픽셀 좌표로 표시된 감지된 얼굴의 경계 상자입니다. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: 얼굴 감지 신뢰도(0–1). example: 0.732973 age: type: number format: float description: >- 감지된 얼굴의 모델 추정 연령(세 단위)입니다. 정보 제공용일 뿐이며 라이브니스 결정에는 영향을 미치지 않습니다. example: 26.91 gender: type: string description: >- 감지된 얼굴의 모델 예측 성별(`male` 또는 `female`)입니다. 정보 제공용입니다. example: male race: type: string nullable: true description: 예약된 필드 — 이 endpoint의 응답에서는 항상 `null`입니다. example: null description: 감지된 얼굴당 항목 1개입니다. 가장 큰 얼굴이 평가 대상이 됩니다. best_angle: type: integer nullable: true description: >- 가장 우수한 얼굴 감지를 생성한 회전 각도(도). `rotate_image=true`로 방향을 수정한 경우에만 0이 아닙니다. example: 0 warnings: type: array description: >- 위험 신호. `error` 심각도(거부): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE`(임계값 이하 점수), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. `warning` 심각도(검토, 거부되지 않음): `MULTIPLE_FACES_DETECTED`. `information` 심각도(거부되지 않음): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` — 동일한 얼굴이 이미 다른 승인된 세션에 나타났습니다. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: 기계 판독 가능한 위험 코드입니다. feature: type: string enum: - LIVENESS description: 경고를 발생시킨 기능입니다. 이 endpoint에서는 항상 `LIVENESS`입니다. additional_data: type: object nullable: true additionalProperties: true description: >- 대부분의 경고의 경우 `null`입니다. 차단 목록 일치 항목에는 `{blocklisted_session_id, blocklisted_session_number, api_service}`가 포함되며, 중복 일치 항목에는 일치하는 세션을 가리키는 `{duplicated_session_id, duplicated_session_number, api_service}`가 포함됩니다. log_type: type: string enum: - error - warning - information description: >- 심각도입니다. `error` 경고는 `status`를 `Declined`로 변경합니다. `warning` 및 `information` 항목은 참고용이며 단독으로 거부되지 않습니다. short_description: type: string description: 사람이 읽을 수 있는 한 줄의 위험 요약입니다. long_description: type: string description: 위험에 대한 사람이 읽기 쉬운 설명입니다. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- 감지된 얼굴의 촬영 품질 점수(0–100으로 정규화됨). 모델이 신뢰할 수 있는 값을 생성할 수 없는 경우 `null`입니다. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: 감지된 얼굴의 밝기로, 0–100으로 정규화됩니다. 사용할 수 없는 경우 `null`입니다. example: 50.33 vendor_data: type: string nullable: true description: 전송한 `vendor_data`의 에코 값 또는 `null`입니다. metadata: type: object nullable: true additionalProperties: true description: 전송한 `metadata` 객체의 에코 값 또는 `null`입니다. created_at: type: string format: date-time description: >- 응답이 생성된 시점의 ISO 8601 타임스탬프(UTC)(예: `2026-06-12T01:04:42.763237+00:00`)입니다. '400': description: >- 유효성 검사 오류입니다. `user_image`가 누락되었거나, 5 MB를 초과하거나, 지원되지 않는 확장자이거나, 서버 측 이미지 디코딩에 실패했거나, 옵션이 범위를 벗어난 경우 반환됩니다. 필드 오류는 DRF의 `{field: [messages]}` 봉투를 사용하며, 이미지 디코딩 실패는 `{"error": ...}`를 사용합니다. content: application/json: examples: Missing image: summary: 폼 데이터에 `user_image`가 포함되지 않음 value: user_image: - No file was submitted. Invalid image format: summary: 허용된 확장자이지만 디코딩할 수 없는 이미지 콘텐츠입니다. value: error: Invalid user image format. code: invalid_image Unsupported file extension: summary: tiff/jpg/jpeg/png/webp 이외의 파일 확장자 value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: 업로드가 5MB 제한을 초과함 value: user_image: - File size should not exceed 5 MB '403': description: >- 권한이 거부되었습니다. `x-api-key` 헤더가 누락되었거나 호출한 조직의 잔액이 호출 비용을 충당할 수 없을 때 반환됩니다. 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 키가 누락된 경우 `{"detail": ...}`과 함께 `403`을 반환하고, 잘못되었거나 취소되었거나 만료된 키는 `401`을 반환합니다. 크레딧이 부족한 경우 어떠한 이미지 처리도 진행되기 전에 `{"error": ...}`과 함께 `403`을 반환합니다. content: application/json: examples: Missing or invalid API key: summary: '`x-api-key` 헤더가 없거나, 키가 유효하지 않거나 해지되었습니다' value: detail: You do not have permission to perform this action. Not enough credits: summary: 조직 잔액이 호출 비용을 충당할 수 없습니다 value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- 속도 제한을 초과했습니다. POST/PATCH/DELETE endpoint는 API 키당 분당 300회의 쓰기 요청 한도를 공유합니다(거래 생성 및 이벤트 수집은 별도로 600회 한도 적용). 응답에는 `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` 헤더가 포함됩니다. content: application/json: examples: Write rate limit exceeded: summary: 현재 분 동안 300건을 초과하는 쓰기 요청 발생 value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'face_liveness_score_decline_threshold=30' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.passive_liveness.check( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "withdrawal"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.passiveLiveness.check({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"withdrawal\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.PassiveLivenessCheckParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "withdrawal")) .build()); System.out.println(result); - lang: php label: PHP source: |- passiveLiveness->check([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'withdrawal'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.passive_liveness.check( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "withdrawal" }, }); 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.