> ## 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のライブネス検知は、パッシブとアクティブの方式でディープフェイク、マスク、なりすましを検出します。精度99.9%、iBetaテスト済み、1回$0.10から。
Didit ライブネス検知は、パッシブ、3Dアクション、フラッシュのいずれかの方式で、カメラの前にいるのが印刷された写真、画面の再生、マスク、ディープフェイクではなく、実在する生きた人物であることを確認する機能です。**99.9%の精度**を達成し、誤受入率（FAR）は\*\*0.1%\*\*未満です。
ライブネスの連携プロンプト
Copy prompt to clipboard
\
\````# 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````
\
Paste into
ホスト型のユーザーフローを扱うAcademyのレッスンでは、8:49でライブネスのセルフィーに到達し、9:16からパッシブ、3Dフラッシュ、3Dアクションの各方式を紹介しています。[ライブネスのセルフィー — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## ライブネス検知の方式Diditのプラットフォームは、セキュリティ要件とユーザー体験に合わせて使い分けられる、3種類のアンチスプーフィング技術を実装しています。
| 方式 |
説明 |
セキュリティレベル |
適した用途 |
| **`3D Action & Flash`** |
• 多要素の生体認証と、**ランダムな動作シーケンス**および**動的な光パターン解析**を組み合わせます。\
• 開始時に、**まばたき**や**うなずき**などの簡単な動作を求め、リアルタイムのやり取りを確認します。\
• 同時に、顔に一連の光パターンを投影し、その**反射**を解析して顔の立体構造を確認します。\
• **ディープラーニングアルゴリズム**が微表情と光の反射応答を調べ、生きた人物がいることを検証します。\
• 行動（動作）と物理（光による奥行き）の手がかりを組み合わせるため、**最高のセキュリティ**を実現し、静止画、動画、高度なマスクでさえなりすましはほぼ不可能です。
|
最高 |
銀行、医療、行政のアプリケーション |
| **`3D Flash`** |
• **動的な光パターン解析**により、ユーザー操作なしで顔の立体形状を検証します。\
• 毎秒**30フレーム**を超える速度で一連の光パターンを顔に投影し、反射を解析して**深度マップ**を作成します。\
• この深度マップで顔の立体構造を確認し、平面の画像や2Dのなりすましと区別します。\
• **スムーズな体験**を保ちながら、写真や画面などのプレゼンテーション攻撃に対して**高いセキュリティ**を維持します。\
|
高 |
金融サービス、アカウントアクセス、本人確認 |
| **`Passive Liveness`** |
• **1フレームのディープラーニング解析**でライブネスの兆候を検出します。\
• 画像の**アーティファクト**や**テクスチャパターン**などの微妙な指標を調べ、本物の顔となりすましを区別します。\
• **畳み込みニューラルネットワーク（CNN）**が顔の特徴を検証し、印刷された写真やデジタル画面に由来する異常を特定します。\
• **高速で便利**な検証ですが、セキュリティは**標準的**で、低リスクのユースケースに適しています。\
|
標準 |
摩擦の少ないシナリオ、一般消費者向けアプリケーション |
> [!NOTE]
>
> **3D Flash と 3D Action & Flash の高度なセキュリティ:**
>
> > * これらの方式は、**高品質なマスク**、**ディープフェイク**、**動画の再生**といった**高度ななりすまし攻撃**を退けるように設計されています。
> > * 動的な光パターンを投影してその反射を解析することで、光が**本物の3Dの顔**と、平面や人工物の表面とでどう異なる反応をするかを検出します。
> > * **3D Action & Flash**方式は、ランダムな動作（例：まばたきやうなずき）で追加のセキュリティ層を設け、録画済みのメディアや合成されたアイデンティティでは再現できない**リアルタイムの行動反応**を必要とします。
> > * **高い精度**と**低い誤受入率**が実証されており、これらの方式は重要度の高い環境に最適です。いずれの方式も、複数のセキュリティ要素をリアルタイムで評価する独自のアルゴリズムに基づいて、\*\*正規化されたライブネススコア（0〜100%）\*\*を生成します。### 設定可能なしきい値ライブネススコアのしきい値を変えることで、セキュリティレベルをカスタマイズできます。例えば次のように設定します。> [!NOTE]
>
> これらのしきい値は、**リスク許容度**と**セキュリティ要件**に合わせて調整でき、ユースケースを問わず柔軟に対応できます。## 再試行と具体的なフィードバックDiditのセッションでは、**修正可能な理由**（照明不足、顔が中央にない、遮蔽物、境界的なスコア）でライブネスの撮影に失敗しても、すぐには拒否されません。ユーザーは、設定可能な試行回数まで、**具体的なガイダンスとともに再試行**するよう求められます。* **試行回数の上限** — `face_liveness_max_attempts`は、1セッションあたりのライブネス送信の合計回数を制御します。既定は**3**（最初の1回と再試行2回）で、ワークフローのノードごとに設定できます（範囲は1〜3）。
* **再試行のフィードバック** — 試行回数が残っている間、再試行可能な失敗ではユーザーはライブネスのステップにとどまり、具体的な`feedback_codes`を含む本文が返されます（WebおよびモバイルSDKは、これを自動的にコーチングメッセージとして表示します）。
```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
}
```
* **再試行可能なコード** — `LOW_FACE_LUMINANCE`（暗すぎる）、`HIGH_FACE_LUMINANCE`（明るすぎる）、`NO_FACE_DETECTED`、`LOW_FACE_QUALITY`、`HIGH_FACE_OCCLUSION`、`LOW_LIVENESS_SCORE`、`MULTIPLE_FACES_DETECTED`、`AGE_NOT_DETECTED`。
* **撮影条件での再試行の保証** — `LOW_FACE_LUMINANCE`、`HIGH_FACE_LUMINANCE`、`LOW_FACE_QUALITY`、`HIGH_FACE_OCCLUSION`、`NO_FACE_DETECTED`は、本人ではなく、ユーザーがいる環境の状態を表します。これらのコードだけで試行が失敗した場合、ワークフローが`face_liveness_max_attempts: 1`に設定されていても、ユーザーは上記のコーチングメッセージとともに必ず2回目の試行を行えます。それ以外のコードは、設定した試行回数の上限にそのまま従います。
* **上限到達と不正** — 試行回数の上限に達すると、算出されたステータス（`Declined`または`In Review`）が適用されます。確認されたプレゼンテーション攻撃（`LIVENESS_FACE_ATTACK`）、ブロックリストへのヒット、重複した顔は**即座に拒否**され、再試行はされません。> [!NOTE]
>
> 再試行は**セッションフロー**にのみ適用されます。スタンドアロンの`POST /v3/passive-liveness/`エンドポイントはステートレスで1回限りです。再試行の上限はなく、結果が直接返されます。## 仕組み**1. ビデオセルフィーの撮影**ユーザーは、選択されたライブネス方式に合わせた**シンプルで直感的なインターフェース**で案内されます。| チェック | 説明 |
| - | - |
| **リアルタイムのフィードバック** | 適切な照明、位置、フレーミングを確保します |
| **品質チェック** | ぼけ、反射、顔の見え方の最適さを監視します |
| **アダプティブキャプチャ** | さまざまなデバイスの性能やネットワーク状況に合わせて調整します |
| **方式ごとのガイダンス** | 方式固有の指示（例：3Dアクションでの「今まばたきしてください」）を表示します |**2. ライブネス検知の解析**高度なアルゴリズムが、撮影したメディアを**リアルタイム**で処理し、なりすましの試みを検出します。解析内容は方式ごとに異なります。> **3D Action & Flash**
>
> * ユーザーの動作（例：**まばたき**や**うなずき**）が正しく、かつリアルタイムで行われたかを検証します
> * **光パターンの反射**を解析して、顔の立体構造を検証します
> * ディープラーニングで**微表情**やその他の行動の手がかりを評価します
> * 行動と物理の両方の信号を組み合わせ、**最強のなりすまし耐性**を実現します> **3D Flash**
>
> * 30+ FPSで一連の**光パターンの反射**を処理し、詳細な**深度マップ**を作成します
> * 顔の3D特性を確認し、平面や2Dのなりすましと区別します
> * ユーザー操作は不要で、ユーザーから見て完全に**パッシブ**です> **Passive Liveness**
>
> * 1フレームに**ディープラーニング**を適用して、**テクスチャパターン**と**アーティファクト**を検出します
> * 畳み込みニューラルネットワーク（CNN）が顔の特徴を検証し、異常を特定します
> * 最速の方式で、**写真1枚の撮影**で動作します多層的な検知により、写真、画面、マスク、ディープフェイクなどの**プレゼンテーション攻撃**を特定します。**3. 結果の処理と検証**システムはライブネススコアを**設定したしきい値**と比較し、結果を即座に提供します。| 出力 | 説明 |
| - | - |
| **ライブネススコア** | 正規化された0〜100%の信頼度スコア |
| **判定** | しきい値に基づく、承認、拒否、またはレビュー中 |
| **方式** | 使用されたライブネス方式（`passive`、`flash`、`action_flash`） |
| **参照画像** | ライブネスチェックに使われた撮影フレーム |
| **警告** | 検出された異常（例：低品質、なりすましの可能性を示す指標） |結果は**APIレスポンス**、**Webhook**で配信されるほか、コンプライアンス用の詳細な監査ログとともに**Business Console**でも確認できます。> [!TIP]
>
> ライブネス方式は、[Business Console](https://docs.didit.me/console/workflows.md)でワークフローごとに設定できます。リスク要件に応じて、ワークフローごとに異なる方式を使えます。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.