> ## 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. # Deteksi Liveness Pasif: API Deteksi Deepfake > Didit mendeteksi masker, cetakan, replay, dan deepfake dari satu gambar. Pasif, di bawah 2s, bayar per penggunaan, tanpa minimum bulanan. ## OpenAPI ````yaml id/openapi-25.json POST /v3/passive-liveness/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API Verifikasi Identitas. Lakukan autentikasi dengan header x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/passive-liveness/: post: tags: - Standalone APIs summary: Liveness Pasif description: >- Deteksi serangan presentasi — foto cetak, pemutaran ulang layar, topeng, deepfake — dari satu gambar wajah. Tidak memerlukan video, gerakan, atau interaksi pengguna. **Cara kerjanya.** Gambar dianalisis oleh model biometrik; wajah terbesar yang terdeteksi dievaluasi dan `score` liveness (0–100) dihitung. `status` bernilai `Declined` ketika salah satu peringatan dengan tingkat keparahan `error` terpicu: - `NO_FACE_DETECTED` — model liveness tidak menemukan wajah, - `LOW_LIVENESS_SCORE` — skor sama dengan atau di bawah `face_liveness_score_decline_threshold` (default `30`), - `LIVENESS_FACE_ATTACK` — model mendeteksi serangan presentasi, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` — wajah cocok dengan entri pada daftar blokir wajah Anda. `MULTIPLE_FACES_DETECTED` adalah sinyal tingkat keparahan `warning` (tidak menolak), dan `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` adalah sinyal tingkat keparahan `information` bahwa wajah yang sama telah muncul di sesi lain yang disetujui (sinyal ini tidak pernah menolak). `face_quality` dan `face_luminance` (0–100, nullable) menjelaskan kualitas pengambilan gambar. **Skrining daftar blokir dan duplikat.** Berjalan pada **setiap** panggilan — dengan atau tanpa `save_api_request` — dengan mencocokkan wajah yang terdeteksi terhadap indeks pencarian wajah aplikasi Anda. Wajah sebelumnya dengan `vendor_data` yang sama dikecualikan dari seluruh pencarian indeks — sehingga menjalankan ulang liveness untuk pengguna yang sama tidak memicu `DUPLICATED_FACE`, dan wajah dalam daftar blokir yang berasal dari sesi dengan `vendor_data` milik pemanggil sendiri juga TIDAK ditandai (skrining `FACE_IN_BLOCKLIST` dilewati untuk wajah dengan `vendor_data` yang sama). **Penagihan.** Setiap respons `200` menggunakan satu kredit Passive Liveness API (dibayar dari kredit paket atau saldo isi ulang Anda). Saldo yang tidak mencukupi mengembalikan `403` sebelum pemrosesan gambar apa pun. **Persistensi sesi dan pendaftaran wajah (`save_api_request`, default `true`).** Jika bernilai `true`, panggilan disimpan sebagai sesi bertipe API (Business Console, `GET /v3/session/{sessionId}/decision/` melalui `request_id` yang dikembalikan, webhook `status.updated`), gambar referensi dan potongan wajah disimpan, dan wajah yang terdeteksi **didaftarkan ke dalam indeks pencarian wajah Anda** sehingga panggilan Pencarian Wajah dan pemeriksaan duplikat di kemudian hari dapat mencocokkannya. Jika bernilai `false`, panggilan bersifat sekali pakai: tidak ada yang disimpan dan wajah tidak didaftarkan (skrining daftar blokir/duplikat tetap berjalan). **Sandbox.** Kunci API sandbox melewati semua pemrosesan dan penagihan: setelah validasi permintaan (input yang salah tetap mengembalikan `400`), endpoint mengembalikan payload tiruan `Approved` statis, tidak ada sesi yang disimpan, dan tidak ada kredit yang digunakan. **Autentikasi.** Kirim kunci API aplikasi Anda di header `x-api-key`. Kredensial yang hilang atau tidak valid mengembalikan `403` (`{"detail": "You do not have permission to perform this action."}`) — API ini tidak pernah mengembalikan `401`. **Batas laju.** Kuota penulisan bersama sebesar 300 permintaan/menit per kunci API di seluruh endpoint POST/PATCH/DELETE; melampauinya akan mengembalikan `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: >- Gambar wajah menghadap ke depan (misalnya swafoto). Ekstensi yang diizinkan: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Ukuran unggahan maksimum: **5 MB** (file yang lebih besar ditolak dengan `400`). Gambar otomatis dikompresi menjadi ~0.5 MB sebelum diproses, sehingga resolusi yang sangat tinggi tidak meningkatkan akurasi. Gambar harus memuat satu subjek — jika terdapat beberapa wajah, wajah terbesar yang akan dievaluasi dan peringatan `MULTIPLE_FACES_DETECTED` ditambahkan. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Ambang batas skor liveness (0–100). Skor terhitung **pada atau di bawah** nilai ini mengeluarkan peringatan `LOW_LIVENESS_SCORE` dan menetapkan `status` ke `Declined`. Default `30`; naikkan untuk postur anti-spoofing yang lebih ketat. Nilai di luar 0–100 mengembalikan `400`. example: 30 rotate_image: type: boolean default: false description: >- Jika `true`, layanan mencoba rotasi 90 derajat dari input dan menggunakan orientasi yang menghasilkan deteksi wajah terbaik. Berguna saat orientasi EXIF tidak ada. Menambah latensi. example: false save_api_request: type: boolean default: true description: >- Jika `true` (default), menyimpan panggilan sebagai sesi tipe API, menyimpan gambar wajah, memancarkan webhook `status.updated`, dan mendaftarkan wajah yang terdeteksi ke dalam indeks pencarian wajah Anda. Jika `false`, panggilan bersifat sekali jalan — tidak ada yang disimpan dan wajah tidak didaftarkan. Skrining daftar blokir dan duplikat tetap berjalan di kedua kondisi. example: true vendor_data: type: string description: >- Pengidentifikasi buram opsional (ID pengguna, email, UUID Anda…) yang disimpan pada sesi yang dipertahankan dan dikembalikan. Juga digunakan untuk mengecualikan sesi sebelumnya dengan `vendor_data` yang sama dari pemeriksaan wajah duplikat, sehingga verifikasi ulang pengguna yang sama tidak memicu `DUPLICATED_FACE`. example: user-123 metadata: type: object additionalProperties: true description: >- Objek JSON opsional yang disimpan bersama sesi (saat `save_api_request=true`) dan dikembalikan. Dalam permintaan multipart, kirimkan sebagai kolom string berenkode JSON — kolom ini akan diuraikan menjadi sebuah objek. 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: >- Deteksi liveness pasif selesai. `liveness.score` adalah tingkat keyakinan model 0–100 bahwa gambar tersebut menampilkan orang sungguhan; `status` bernilai `Approved` kecuali jika peringatan berbobot `error` terpicu. Wajah hasil spoofing atau yang masuk daftar blokir tetap mengembalikan `200` — periksa `liveness.status` dan `liveness.warnings`, bukan hanya kode HTTP. Ketika `save_api_request=true`, `request_id` adalah ID sesi yang disimpan. content: application/json: examples: Approved: summary: Wajah nyata — tidak ada peringatan 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: >- Model menandai adanya spoofing (cetak, tayang ulang, topeng…) 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: Wajah nyata, tetapi cocok dengan entri daftar blokir 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: >- ID sesi yang disimpan saat `save_api_request=true` (dapat digunakan dengan `GET /v3/session/{sessionId}/decision/`); jika tidak, berupa UUID korelasi sementara. liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined` ketika setidaknya satu peringatan berperingkat `error` terpicu (tidak ada wajah, skor rendah, serangan presentasi, atau kecocokan daftar blokir); `Approved` jika tidak. Entri `warning`/`information` (banyak wajah, duplikat) tidak pernah menolak dengan sendirinya. method: type: string enum: - PASSIVE description: Selalu `PASSIVE` untuk endpoint ini. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Keyakinan liveness (0–100, dua desimal) bahwa gambar menampilkan orang sungguhan, bukan spoofing. `null` jika model tidak mengembalikan keyakinan. example: 95 user_image: type: object description: Hasil deteksi wajah untuk gambar yang dikirimkan. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Bounding box wajah yang terdeteksi sebagai koordinat piksel `[x_min, y_min, x_max, y_max]` pada gambar yang diproses. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Skor keyakinan deteksi wajah (0–1). example: 0.732973 age: type: number format: float description: >- Usia yang diestimasi model dari wajah yang terdeteksi, dalam tahun. Hanya bersifat informasi — ini tidak memengaruhi keputusan liveness. example: 26.91 gender: type: string description: >- Jenis kelamin yang diprediksi oleh model dari wajah yang terdeteksi (`male` atau `female`). Hanya bersifat informasi. example: male race: type: string nullable: true description: >- Kolom yang dicadangkan — selalu bernilai `null` dalam respons dari endpoint ini. example: null description: >- Satu entri per wajah yang terdeteksi. Wajah terbesar adalah wajah yang dievaluasi. best_angle: type: integer nullable: true description: >- Rotasi (derajat) yang menghasilkan deteksi wajah terbaik; bernilai bukan nol hanya ketika `rotate_image=true` mengoreksi orientasi. example: 0 warnings: type: array description: >- Sinyal risiko. Keparahan `error` (penolakan): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (skor pada atau di bawah ambang batas), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Keparahan `warning` (peninjauan, tanpa penolakan): `MULTIPLE_FACES_DETECTED`. Keparahan `information` (tanpa penolakan): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` — wajah yang sama telah muncul di sesi lain yang disetujui. 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: Kode risiko yang dapat dibaca mesin. feature: type: string enum: - LIVENESS description: >- Fitur yang memunculkan peringatan. Selalu `LIVENESS` pada endpoint ini. additional_data: type: object nullable: true additionalProperties: true description: >- `null` untuk sebagian besar peringatan. Kecocokan daftar blokir memuat `{blocklisted_session_id, blocklisted_session_number, api_service}`; kecocokan duplikat memuat `{duplicated_session_id, duplicated_session_number, api_service}` yang mengarah ke sesi yang cocok. log_type: type: string enum: - error - warning - information description: >- Tingkat keparahan. Peringatan `error` mendorong `status` menjadi `Declined`; entri `warning` dan `information` bersifat anjuran dan tidak pernah menolak dengan sendirinya. short_description: type: string description: >- Ringkasan satu baris yang dapat dibaca manusia tentang risiko. long_description: type: string description: Penjelasan risiko yang mudah dibaca manusia. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Skor kualitas pengambilan wajah yang terdeteksi, dinormalisasi ke 0–100. `null` jika model tidak dapat menghasilkan nilai yang andal. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Kecerahan wajah yang terdeteksi, dinormalisasi ke 0–100. `null` jika tidak tersedia. example: 50.33 vendor_data: type: string nullable: true description: Salinan `vendor_data` yang Anda kirimkan, atau `null`. metadata: type: object nullable: true additionalProperties: true description: Salinan objek `metadata` yang Anda kirimkan, atau `null`. created_at: type: string format: date-time description: >- Stempel waktu ISO 8601 (UTC) saat respons dibuat, misalnya `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Kesalahan validasi. Dikembalikan ketika `user_image` tidak ada, melebihi 5 MB, memiliki ekstensi yang tidak didukung, gagal dalam decoding gambar di sisi server, atau ketika sebuah opsi berada di luar rentang. Kesalahan kolom menggunakan envelope `{field: [messages]}` milik DRF; kegagalan decoding gambar menggunakan `{"error": ...}`. content: application/json: examples: Missing image: summary: '`user_image` tidak disertakan dalam data formulir' value: user_image: - No file was submitted. Invalid image format: summary: Ekstensi diizinkan tetapi konten gambar tidak dapat didekode value: error: Invalid user image format. code: invalid_image Unsupported file extension: summary: Ekstensi file di luar 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: Unggahan melebihi batas 5 MB value: user_image: - File size should not exceed 5 MB '403': description: >- Izin ditolak. Dikembalikan ketika header `x-api-key` tidak ada, dan juga ketika saldo organisasi pemanggil tidak dapat mencukupi biaya panggilan tersebut; kunci yang salah, dicabut, atau kedaluwarsa mengembalikan `401`. Kunci yang tidak ada mengembalikan `403` dengan `{"detail": ...}`; kunci yang salah, dicabut, atau kedaluwarsa mengembalikan `401`. Kekurangan kredit mengembalikan `403` dengan `{"error": ...}` sebelum pemrosesan gambar apa pun terjadi. content: application/json: examples: Missing or invalid API key: summary: >- Tidak ada header `x-api-key`, atau kuncinya tidak valid/dicabut value: detail: You do not have permission to perform this action. Not enough credits: summary: Saldo organisasi tidak mencukupi untuk panggilan ini value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Batas laju terlampaui. Endpoint POST/PATCH/DELETE berbagi anggaran 300 permintaan penulisan per menit per kunci API (pembuatan transaksi dan ingesti event memiliki anggaran terpisah sebesar 600). Respons menyertakan header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, dan `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Lebih dari 300 permintaan tulis pada menit ini 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: >- Kunci API aplikasi Anda, dari Developers -> API keys di Business Console. Kunci utama memiliki akses penuh. Kunci bernama dapat diberi cakupan: none, read, atau write per sumber daya, dibatasi pada beberapa alur kerja atau pada sesi yang disetujui, pada daftar alamat IP, dan pada tanggal kedaluwarsa. 401 berarti kuncinya salah, dicabut, atau kedaluwarsa; 403 berarti tidak ada kunci yang dikirimkan, kunci tidak memiliki akses ke sumber daya atau tindakan ini, atau permintaan datang dari alamat di luar daftar IP-nya; 404 pada rute sesi berarti sesi berada di luar alur kerja atau status kunci tersebut. Kunci tanpa akses media menerima URL gambar, video, dan PDF sebagai null, dan kunci tanpa izin tulis sesi menerima tautan sesi dan token sebagai null. Lihat https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.