> ## 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.

# ライブネスレポート：スコア・検出方式・顔照合結果

> Didit のライブネスレポートの読み方を解説。ステータス、信頼度スコア、検出方式、年齢推定、セッション間の顔照合結果と、レスポンス内の表示箇所を確認できます。

## 概要

**ライブネスレポート**には、カメラの前にいるのが印刷された写真、画面の再生映像、ディープフェイクではなく、実在する生身の人物であることを検証する過程でDiditが確認したすべての情報が記録されます。レポートには、ライブネス検知の方式、0〜100の信頼度スコア、基準となるセルフィーと撮影動画、オプションの年齢推定、パッシブライブネスの品質指標、そしてアプリケーションの履歴およびブロックリストに対するセッション横断の顔照合結果が含まれます。

レポートは、ユーザーがワークフロー内のライブネスステップを完了した後(またはスタンドアロンの顔エンドポイントを呼び出した後)に生成されます。Diditは3つのライブネス検知方式(アクティブ3D、フラッシュ、パッシブ)のいずれかを実行し、撮影データをスコアリングし、既知のなりすましパターンをスクリーニングしたうえで、その顔をアプリケーションでこれまでに確認した他のすべての顔と生体認証により照合します。

各レポートには、セッション全体のステータスとは独立した独自の`status`があり、ライブネスステップ単体の判定結果を表します。

* **承認済み**:顔が検出され、ライブネススコアがレビューのしきい値を上回り、自動却下の警告が発生していない状態です。
* **レビュー中**:レビューに振り分けられる警告が1つ以上発生したか、スコアがレビューのしきい値以下で却下のしきい値を上回っている状態です。
* **却下**:自動却下の条件(`NO_FACE_DETECTED`、`LIVENESS_FACE_ATTACK`、`FACE_IN_BLOCKLIST`、または年齢推定フローにおける年齢関連のリスク)が発生したか、設定可能な警告が却下に振り分けられたか、スコアが却下のしきい値以下である状態です。
* **未完了**:ユーザーがライブネスステップを完了していない状態です。

## APIレスポンスでの表示箇所

ライブネスレポートは、`GET /v3/session/{sessionId}/decision/`のレスポンスに`liveness_checks[]`として含まれます。これは**常にJSON配列**であり、単一の`liveness`オブジェクトになることはありません。ワークフローでライブネス検知が複数回実行される場合(たとえば最初のチェックと再撮影)には、複数のエントリーが含まれます。

* **セッション判定API**:`GET /v3/session/{sessionId}/decision/`はトップレベルで`liveness_checks[]`を返します。[セッション判定の取得](https://docs.didit.me/ja/sessions-api/retrieve-session.md)を参照してください。
* **Webhook**:ステップがデータを生成すると、`session.status.updated`のペイロードに同じ`liveness_checks[]`配列が含まれます。[Webhook](https://docs.didit.me/ja/integration/webhooks.md)を参照してください。
* **スタンドアロンのライブネスAPI**:[ライブネスのスタンドアロンAPI](https://docs.didit.me/ja/standalone-apis/passive-liveness.md)を参照してください。

> [!NOTE]
>
> `response.liveness_checks[0]`を読み取り、配列を反復処理してください。一部の古いチュートリアルで言及されている単一の`liveness`形式は、v3の判定エンドポイントには存在しません。

## スキーマ

フィールドごとの正式なスキーマは、[データモデル](https://docs.didit.me/ja/reference/data-models.md#ライブネスチェック)リファレンスページに掲載されています。以下のフィールドは、その正式なスキーマと同じ内容です。

| フィールド | 型 | 説明 |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | ライブネスステップのステータスです(下記参照)。 |
| `node_id` | string \| null | このレポートを生成したワークフローグラフのノードです。 |
| `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | このキャプチャを生成したライブネス方式です。 |
| `score` | number 0–100 \| null | ライブネスの信頼度スコアで、小数点以下2桁に丸められます。 |
| `reference_image` | string (署名付きURL) \| null | キャプチャから抽出された基準セルフィーです。有効期間が限られた署名付きURLです。 |
| `video_url` | string (署名付きURL) \| null | ライブネスキャプチャの動画全体です(アクティブ方式)。有効期間が限られた署名付きURLです。 |
| `age_estimation` | number \| null | 基準画像内で最も大きく写っている顔の推定年齢(歳)です。 |
| `face_quality` | number 0–100 \| null | パッシブライブネスの顔画像品質で、パーセンテージに正規化されています。`method = "PASSIVE"`の場合にのみ値が入ります。 |
| `face_luminance` | number 0–100 \| null | パッシブライブネスの顔の輝度で、0–255からパーセンテージに正規化されています。`method = "PASSIVE"`の場合にのみ値が入ります。 |
| `matches[]` | array | セッション横断の顔一致です(下記参照)。 |
| `warnings[]` | array | モジュールレベルの警告です。[ライブネスの警告](https://docs.didit.me/ja/core-technology/liveness/warnings-liveness.md)を参照してください。各エントリは[警告オブジェクト](https://docs.didit.me/ja/reference/data-models.md#警告オブジェクト)の形式(`feature`、`risk`、`additional_data`、`log_type`、`short_description`、`long_description`、`node_id`)に従います。 |

### セッション横断の顔一致

`matches[]`には、アプリケーションの履歴にある顔のうち、このセルフィーとの生体認証による類似度がしきい値を超えたものが一覧表示されます。最大5件で、ブロックリストと許可リストに登録された顔が先に並び、その後は類似度の高い順に並びます。照合対象となるのは、ブロックリストに登録された顔、許可リストに登録された顔、`Approved`のセッションの顔、およびベンダーユーザーに対してインポートされた顔です。同一ユーザーに属する顔(同じ`vendor_data`、または利用可能な場合は同じベンダーユーザー)は、重複検出とブロックリストスクリーニングの両方を含む検索**全体**から除外されます。

各エントリには以下が含まれます。

| フィールド | 型 | 説明 |
| - | - | - |
| `session_id` | string (UUID) \| null | 一致したセッションです。`source`が`imported`または`list_entry`の場合は`null`です。 |
| `session_number` | number \| null | 一致したセッションの連番です。セッション以外のソースの場合は`null`です。 |
| `similarity_percentage` | number 0–100 | 生体認証による類似度スコアで、0–100の範囲に収められます。 |
| `vendor_data` | string \| null | 一致したセッション(インポートされた顔の場合はベンダーユーザー)に設定した参照データです。 |
| `verification_date` | string (ISO 8601) \| null | 一致したセッション(またはインポートされた顔)が作成された日時です。 |
| `user_details` | object \| null | 一致したセッションのKYCから取得した`{ full_name, document_type, document_number }`です。インポートされた顔では`full_name`のみが入ります(2つの書類フィールドは`null`です)。詳細情報が登録されていない場合は`null`です。 |
| `match_image_url` | string (署名付きURL) \| null | 一致したセッション、インポートされた顔、またはリストエントリの基準顔画像です。 |
| `status` | string \| null | 一致したセッションのステータスです(例: `"Approved"`)。セッション以外のソースの場合は`null`です。 |
| `is_blocklisted` | boolean | 一致した顔が顔のブロックリストに登録されている場合は`true`です。 |
| `is_allowlisted` | boolean | 一致した顔が顔の許可リストに登録されている場合は`true`です(重複顔に対するアクションはスキップされます)。 |
| `api_service` | string \| null | 一致した顔がスタンドアロンのAPI呼び出しから取得された場合に設定されます(例: `"PASSIVE_LIVENESS"`)。ワークフローのセッションとセッション以外のソースの場合は`null`です。 |
| `source` | `"session" \| "imported" \| "list_entry"` | 一致した顔の取得元です。別の認証セッション、ベンダーユーザーに紐づけてアップロードされた顔、または組織が管理する許可リスト・ブロックリストの顔のいずれかです。 |

## ステータス値

ステータスは、共通の機能ステータス列挙型(`FeatureStatusChoices`)に基づきます。

| ステータス | 意味 | 後続処理への影響 |
| - | - | - |
| `Approved` | 顔が検出され、ライブネススコアがレビューのしきい値を上回り、自動却下の警告が発生していません。 | ライブネスチェックの成功として扱われます。 |
| `In Review` | スコアがレビューのしきい値以下かつ却下のしきい値を上回っているか、レビューに回される警告が発生しました。 | レビュアーが対応するまで、セッションも`In Review`に移行します。 |
| `Declined` | 自動却下のリスク(`NO_FACE_DETECTED`、`LIVENESS_FACE_ATTACK`、`FACE_IN_BLOCKLIST`、または年齢推定フローにおける年齢関連のリスク)が発生したか、設定可能な警告が却下に回されたか、スコアが却下のしきい値以下です。 | 別の承認済みの分岐がワークフローの条件を満たさない限り、セッションは却下されます。 |
| `Not Finished` | ユーザーがライブネスステップを放棄しました(または、再試行可能なキャプチャの失敗が次の試行を待っています)。 | ライブネスの分岐は結果を生成しませんでした。 |
| `Resub Requested` | レビュアーがコンソールからこのステップの再提出をリクエストしました。 | 一時的なステータスで、ユーザーが再キャプチャすると置き換えられます。 |

## 例

### 承認済み: 問題のないACTIVE\_3Dキャプチャ

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### レビュー中: パッシブライブネス、低品質なキャプチャと重複の可能性

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

この例では、顔画像品質(12.4)がデフォルトのレビューしきい値(15)を下回り、輝度(18.7)がデフォルトの最小値(20)を下回っています。さらに、ワークフローで重複する顔が検出された場合のアクションがReviewに設定されています。そのため、3つの警告すべてが`log_type: "warning"`となり、レポートは`In Review`になります。

## セキュリティに関する注意

ライブネス動画とセルフィーは生体データです。署名付きURLは一時的なもので、有効期限があります(デフォルトでは4時間後に失効します)。短期間のみ有効なものとして扱い、キャッシュしたり公開したりしないでください。通常、アプリケーションに必要なのは`status`、`score`、および警告のみです。サーバー上の生体データを最小限に抑えるため、保存するデータはできる限り少なくしてください。

## 関連情報

* [ライブネス検知の警告](https://docs.didit.me/ja/core-technology/liveness/warnings-liveness.md)：警告のenumの全一覧、原因、対処方法。
* [Webhook](https://docs.didit.me/ja/integration/webhooks.md)：レポートを受信するには、`session.status.updated`をリッスンします。
* [データモデル：ライブネスチェック](https://docs.didit.me/ja/reference/data-models.md#ライブネスチェック)：すべてのフィールドを含む正式なスキーマ。
* [顔照合レポート](https://docs.didit.me/ja/core-technology/face-match/report-face-match.md)：書類の顔写真との1:1顔照合を行う、対になるレポート。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.