> ## 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 Deteksi Liveness: Pencegahan Deepfake
> Deteksi deepfake, topeng, dan serangan presentasi dengan deteksi liveness Didit. Akurasi 99.9%, teruji iBeta, bayar per panggilan mulai $0.10.
Deteksi Liveness Didit mengonfirmasi bahwa orang nyata yang masih hidup berada di depan kamera, bukan foto cetak, tayangan ulang layar, topeng, atau deepfake, menggunakan liveness pasif, aksi 3D, atau flash. Solusi ini mencapai **akurasi 99.9%** dengan tingkat penerimaan palsu (FAR) di bawah **0.1%**.
Prompt Integrasi Liveness
Salin prompt ke papan klip
\
\````# Goal
Integrate Didit Liveness Detection (passive / 3D-action / flashing) into your app. Pick ONE mode.
\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow (SDK or session.url). The workflow's LIVENESS feature controls which method runs.
1\. Configure the workflow's liveness method — `face_liveness_method`: "PASSIVE" | "ACTIVE_3D" | "FLASHING" (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.
Decision surface: `liveness_checks[]` array on the decision payload (one entry per liveness node).
\# Mode B — Standalone API (server-to-server, passive only)
Use when you already have a captured selfie and want a one-shot passive-liveness check.
POST https://verification.didit.me/v3/passive-liveness/
multipart/form-data — x-api-key: YOUR_API_KEY
Required: user_image (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted).
curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, liveness: { status, method: "PASSIVE", score, user_image: { entities, best_angle }, warnings, face_quality, face_luminance } }.
When `save_api_request=true` the submitted face is also screened against your blocklist and face index for duplicates — set to `false` to skip enrolment.
\# Status enum (per liveness_checks[].status or liveness.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"
\# Warnings (LogWarningChoices.LIVENESS)
warnings[] risk codes include:
LOW_LIVENESS_SCORE, NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, MULTIPLE_FACES_DETECTED, FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE.
Full catalogue: /core-technology/liveness/warnings-liveness.
\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image, file too large, unsupported extension.
\- status="Declined" with LIVENESS_FACE_ATTACK or LOW_LIVENESS_SCORE — presentation attack suspected; do not approve.
\- FACE_IN_BLOCKLIST / DUPLICATED_FACE — block or route to manual review per your policy.
\- NO_FACE_DETECTED / MULTIPLE_FACES_DETECTED — ask the user to retry with a single, well-framed face.
\# See also
\- Canonical schema: /reference/data-models#liveness-check
\- Per-feature report: /core-technology/liveness/report-liveness
\- Risk catalogue: /core-technology/liveness/warnings-liveness
\- Full integration playbook: /integration/integration-prompt````
\
Tempel ke
Pelajaran Academy tentang alur pengguna yang di-hosting menampilkan swafoto liveness pada menit 8:49, dilanjutkan pada menit 9:16 dengan metode pasif, 3D flash, dan aksi 3D.[Swafoto liveness — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## Metode Deteksi LivenessPlatform kami menerapkan tiga teknologi anti-spoofing yang berbeda, masing-masing disesuaikan dengan kebutuhan keamanan dan pengalaman pengguna yang berbeda:
| Metode |
Deskripsi |
Tingkat Keamanan |
Paling Cocok Untuk |
| **`3D Action & Flash`** |
• Menggabungkan verifikasi biometrik multifaktor dengan **urutan tindakan acak** dan **analisis pola cahaya dinamis**.\
• Pada awal proses, pengguna diminta untuk melakukan tindakan sederhana—seperti **berkedip** atau **mengangguk**—memastikan interaksi waktu nyata.\
• Secara bersamaan, sistem memproyeksikan urutan pola cahaya ke wajah, menganalisis **refleksi** untuk mengonfirmasi struktur tiga dimensi wajah.\
• **Algoritma pembelajaran mendalam** memeriksa ekspresi mikro dan respons refleksi cahaya untuk memverifikasi keberadaan orang yang hidup.\
• Menawarkan **keamanan tertinggi** dengan mengintegrasikan isyarat perilaku (tindakan) dan fisik (kedalaman berbasis cahaya), menjadikannya hampir mustahil untuk dipalsukan dengan gambar statis, video, atau bahkan topeng canggih.
|
Tertinggi |
Perbankan, layanan kesehatan, aplikasi pemerintah |
| **`3D Flash`** |
• Menggunakan **analisis pola cahaya dinamis** untuk memvalidasi topologi wajah tanpa memerlukan interaksi pengguna.\
• Memproyeksikan serangkaian pola cahaya ke wajah pada lebih dari **30 bingkai per detik**, menganalisis refleksi untuk membuat **peta kedalaman**.\
• Peta kedalaman ini mengonfirmasi struktur tiga dimensi wajah, membedakannya dari gambar datar atau spoofing 2D.\
• Memberikan **pengalaman yang mulus** sambil mempertahankan **keamanan tinggi** terhadap serangan presentasi seperti foto atau layar.\
|
Tinggi |
Layanan keuangan, akses akun, verifikasi identitas |
| **`Passive Liveness`** |
• Mengandalkan **analisis pembelajaran mendalam satu bingkai** untuk mendeteksi tanda-tanda liveness.\
• Memeriksa gambar untuk mencari **artefak**, **pola tekstur**, dan indikator halus lainnya yang membedakan wajah asli dari spoofing.\
• **Jaringan saraf konvolusional (CNN)** memvalidasi fitur wajah dan mengidentifikasi anomali, seperti yang berasal dari foto cetak atau layar digital.\
• Menawarkan verifikasi yang **cepat dan praktis** namun memberikan **keamanan standar**, cocok untuk kasus penggunaan berisiko rendah.\
|
Standar |
Skenario dengan hambatan rendah, aplikasi konsumen |
> [!NOTE]
>
> **Keamanan Lanjutan pada 3D Flash dan 3D Action & Flash:**
>
> > * Metode-metode ini dirancang untuk menggagalkan **serangan spoofing canggih**, seperti **topeng berkualitas tinggi**, **deepfake**, dan **pemutaran ulang video**.
> > * Dengan memproyeksikan pola cahaya dinamis dan menganalisis refleksinya, metode ini mendeteksi bagaimana cahaya berinteraksi dengan **wajah 3D nyata** dibandingkan dengan permukaan datar atau artifisial.
> > * Metode **3D Action & Flash** menambahkan lapisan keamanan ekstra dengan tindakan acak (misalnya, berkedip atau mengangguk), yang membutuhkan **respons perilaku waktu nyata** yang tidak dapat ditiru oleh media yang telah direkam sebelumnya atau identitas sintetis.
> > * Terbukti memberikan **akurasi tinggi** dan **tingkat penerimaan palsu yang rendah**, metode-metode ini ideal untuk lingkungan dengan risiko tinggi.Setiap metode menghasilkan **skor liveness ternormalisasi (0-100%)** berdasarkan algoritma milik kami, yang mengevaluasi beberapa faktor keamanan secara waktu nyata.### Ambang Batas yang Dapat DikonfigurasiAnda dapat menyesuaikan tingkat keamanan dengan menetapkan ambang batas yang berbeda untuk skor liveness. Sebagai contoh:> [!NOTE]
>
> Ambang batas ini dapat disesuaikan berdasarkan **toleransi risiko** dan **persyaratan keamanan** Anda, menawarkan fleksibilitas di berbagai kasus penggunaan.## Coba lagi & umpan balik yang dapat ditindaklanjutiDalam sesi Didit, pengambilan liveness yang gagal karena **alasan yang dapat diperbaiki** (pencahayaan buruk, wajah tidak berada di tengah, oklusi, skor mendekati batas) tidak langsung ditolak. Pengguna diminta untuk **mencoba lagi dengan panduan spesifik**, hingga batas jumlah percobaan yang dapat dikonfigurasi.* **Batas percobaan** — `face_liveness_max_attempts` mengontrol jumlah total pengiriman liveness per sesi. Default **3** (satu percobaan awal ditambah dua percobaan ulang), dapat dikonfigurasi per node alur kerja (rentang 1–3).
* **Umpan balik coba lagi** — selama percobaan masih tersisa, kegagalan yang dapat diulang akan mempertahankan pengguna pada langkah liveness dan mengembalikan isi respons yang memuat `feedback_codes` yang dapat ditindaklanjuti (Web dan Mobile SDK menampilkan ini sebagai pesan panduan secara otomatis):
```json theme={null}
{
"detail": "Move to a brighter, evenly lit place and try again.",
"error": "LOW_FACE_LUMINANCE",
"feedback_codes": ["LOW_FACE_LUMINANCE"],
"attempts_used": 1,
"max_attempts": 3
}
```
* **Kode yang dapat diulang** — `LOW_FACE_LUMINANCE` (terlalu gelap), `HIGH_FACE_LUMINANCE` (terlalu terang), `NO_FACE_DETECTED`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `LOW_LIVENESS_SCORE`, `MULTIPLE_FACES_DETECTED`, `AGE_NOT_DETECTED`.
* **Jaminan coba lagi untuk kondisi pengambilan** — `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, dan `NO_FACE_DETECTED` mendeskripsikan ruangan tempat pengguna berada, bukan orangnya. Ketika percobaan gagal hanya karena kode-kode tersebut, pengguna selalu mendapatkan percobaan kedua dengan pesan panduan di atas, bahkan pada alur kerja yang dikonfigurasi dengan `face_liveness_max_attempts: 1`. Setiap kode lainnya tetap mengikuti batas yang dikonfigurasi secara tepat.
* **Batas habis & penipuan** — setelah batas percobaan habis, status yang dihitung akan diterapkan (`Declined` atau `In Review`). Serangan presentasi yang terkonfirmasi (`LIVENESS_FACE_ATTACK`), temuan pada daftar blokir, dan wajah duplikat **segera ditolak** dan tidak pernah diulang.> [!NOTE]
>
> Coba lagi hanya berlaku untuk **alur sesi**. Endpoint mandiri `POST /v3/passive-liveness/` bersifat stateless dan sekali jalan — endpoint ini mengembalikan hasil secara langsung tanpa batas coba lagi.## Cara kerja**1. Pengambilan Video Swafoto**Pengguna dipandu melalui **antarmuka yang sederhana dan intuitif** yang disesuaikan dengan metode liveness yang dipilih.| Pemeriksaan | Deskripsi |
| - | - |
| **Umpan balik real-time** | Memastikan pencahayaan, posisi, dan pembingkaian yang tepat |
| **Pemeriksaan kualitas** | Memantau keburaman, silau, dan visibilitas wajah yang optimal |
| **Pengambilan adaptif** | Menyesuaikan dengan berbagai kemampuan perangkat dan kondisi jaringan |
| **Panduan metode** | Menampilkan instruksi khusus metode (misalnya, "Berkedip sekarang" untuk 3D Action) |**2. Analisis Deteksi Liveness**Algoritma canggih memproses media yang diambil secara **real time** untuk mendeteksi upaya spoofing. Analisis berbeda untuk setiap metode:> [accordion] 3D Action & Flash
>
> * Memverifikasi tindakan pengguna (misalnya, **berkedip** atau **mengangguk**) untuk mengonfirmasi bahwa tindakan tersebut dilakukan dengan benar dan secara langsung
> * Menganalisis **pantulan pola cahaya** untuk memvalidasi struktur tiga dimensi wajah
> * Menggunakan deep learning untuk menilai **ekspresi mikro** dan isyarat perilaku lainnya
> * Menggabungkan sinyal perilaku + fisik untuk **ketahanan spoofing terkuat**> [accordion] 3D Flash
>
> * Memproses urutan **pantulan pola cahaya** pada 30+ FPS untuk membangun **peta kedalaman** yang mendetail
> * Mengonfirmasi properti 3D wajah, membedakannya dari pemalsuan datar atau 2D
> * Tidak memerlukan interaksi pengguna — sepenuhnya **pasif dari sudut pandang pengguna**> [accordion] Passive Liveness
>
> * Menerapkan **deep learning** pada satu bingkai untuk mendeteksi **pola tekstur** dan **artefak**
> * Jaringan saraf konvolusional (CNN) memvalidasi fitur wajah dan mengidentifikasi anomali
> * Metode tercepat — bekerja dengan **pengambilan satu foto**Deteksi berlapis mengidentifikasi **serangan presentasi** termasuk foto, layar, topeng, dan deepfake.**3. Pemrosesan & Verifikasi Hasil**Sistem membandingkan skor liveness dengan **ambang batas yang Anda konfigurasi** dan memberikan hasil secara instan.| Output | Deskripsi |
| - | - |
| **Skor liveness** | Skor keyakinan yang dinormalisasi 0–100% |
| **Keputusan** | Disetujui, Ditolak, atau Dalam Peninjauan berdasarkan ambang batas Anda |
| **Metode** | Metode liveness mana yang digunakan (`passive`, `flash`, `action_flash`) |
| **Gambar referensi** | Bingkai hasil pengambilan yang digunakan untuk pemeriksaan liveness |
| **Peringatan** | Setiap anomali yang terdeteksi (misalnya, kualitas rendah, indikator potensi pemalsuan) |Hasil dikirimkan melalui **respons API**, **webhook**, atau dapat dilihat di **Business Console** dengan log audit terperinci untuk kepatuhan.> [!TIP]
>
> Anda dapat mengonfigurasi metode liveness mana yang akan digunakan per alur kerja di [Business Console](https://docs.didit.me/id/console/workflows.md). Berbagai alur kerja dapat menggunakan metode yang berbeda tergantung pada persyaratan risiko Anda.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.