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

# 顔照合1:1 API: セルフィーと身分証明書の比較

> Didit の顔照合APIは、ライブのセルフィーと身分証明書の顔写真を AI で比較します。1回$0.05の従量課金、毎月$10無料、2秒未満で一致スコアを返します。

Didit の顔照合は、2つの顔を1:1で比較します。通常は、ライブネスチェックで撮影したセルフィーと、ユーザーの身分証明書の顔写真を比較し、0から100の類似度スコアを返します。設定したしきい値によってチェックに合格するかどうかが決まります。スタンドアロンの `POST /v3/face-match/` API は、デフォルトでスコアが30以下の場合に不合格 (Declined) とします。確認結果の読み方に関するアカデミーのレッスンでは、6:16 の章で、実際のセッション内の顔照合チェックを取り上げています。[顔照合 - Didit アカデミー](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

顔照合連携プロンプト
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Face Match (1:1 — compare two faces) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow. Face Match runs alongside ID Verification (uses the document portrait as ref) and Liveness (uses the live selfie as user_image).

1\. Add the FACE_MATCH feature to a workflow that also runs ID_VERIFICATION + LIVENESS (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: `face_matches[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server)
Use when you already have two images and want a one-shot 1:1 similarity score.

POST https://verification.didit.me/v3/face-match/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (live capture) and `ref_image` (reference portrait). JPEG/PNG/WebP/TIFF, max 5 MB each.

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-match/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'ref_image=@./id_portrait.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, face_match: { status, score (0-100), user_image: {entities}, ref_image: {entities}, warnings: [...] } }. `status` is "Approved" when score > face_match_score_decline_threshold (default 30), else "Declined".

\# Status enum (per face_matches[].status / face_match.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.FACEMATCH)
warnings[] risk codes include:
LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-match/warnings-face-match.

\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image or ref_image, file too large, unsupported extension.
\- status="Declined" with LOW_FACE_MATCH_SIMILARITY — the two faces do not match; do not approve.
\- NO_REFERENCE_IMAGE / NO_FACE_DETECTED — capture problems; ask the user to retry.

\# See also
\- Canonical schema: /reference/data-models#face-match
\- Per-feature report: /core-technology/face-match/report-face-match
\- Risk catalogue: /core-technology/face-match/warnings-face-match
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

![本人確認のステップの概要](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-verification-steps.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=42c64546f3495000d7ea3b10c4b5fa50)## リトライと具体的なフィードバックDidit のセッションでは、**修正可能な撮影上の理由** (セルフィーが暗すぎる、ぼやけている、中心からずれている、類似度がぎりぎりであるなど) で顔照合が失敗しても、すぐには不合格になりません。ユーザーは、設定可能な回数まで、**ガイダンスを受けながらやり直す** ように求められます。これは [ライブネス検知](https://docs.didit.me/ja/core-technology/liveness/overview.md) と同じモデルです。* **試行回数の上限** - `face_match_max_attempts` が、セッションあたりの顔照合の送信回数の合計を制御します。デフォルトは **3** (最初の試行1回とリトライ2回) で、ワークフローのノードごとに設定できます (範囲は1～3)。

* **リトライ時のフィードバック** - 試行回数が残っている間は、リトライ可能な失敗の場合、ユーザーはそのステップに留まり、`feedback_codes` が返されます (Web SDK とモバイル SDK は、これらを自動的にコーチングのメッセージとして表示します)。

  ```json theme={null}
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **上限到達後** - 試行回数の上限に達すると、算出されたステータス (`Declined` または `In Review`) が適用されます。> [!NOTE]
>
> リトライが適用されるのは **セッションフロー** だけです。スタンドアロンの `POST /v3/face-match/` エンドポイントはステートレスで1回限りの呼び出しであり、リトライの上限はなく、類似度スコアを直接返します。## 仕組み**1. インテリジェントな撮影**直感的な AI 搭載の撮影システムで、確認プロセスを手間なく開始できます。ユーザーは、リアルタイムの支援を受けながら、身分証明書をアップロードまたは撮影します。| 機能 | 説明 |
| - | - |
| **自動検出** | 書類の種類と発行国を自動的に特定します |
| **リアルタイムのガイダンス** | 最適な位置、照明、ピントのための視覚的な手がかりを表示します |
| **スマート撮影** | 条件が整うと自動で撮影するため、手動でのやり直しは不要です |
| **幅広い対応** | パスポート、運転免許証、国民 ID カード、在留許可証 |> [!NOTE]
>
> *重要な理由*: インテリジェントな撮影によりユーザーの負担が減り、最初の試行から高品質な提出が得られるため、コンバージョン率と信頼性が高まります。**2. 高度なデータ処理**本人データを、比類のない精度で抽出し、検証します。**データ抽出** - 最先端の技術が、すべての主要な項目を処理します。| 機能 | 詳細 |
| - | - |
| **項目の抽出** | 氏名、生年月日、書類番号、発行日と有効期限、国籍など |
| **OCR** | テキストを高精度で読み取る光学文字認識 |
| **MRZ の解析** | 機械読み取りゾーンの解析とバーコードのデコード |**データ検証**:* 目視ゾーン、MRZ、バーコードの間でデータを照合し、整合性を確認します
* 形式とパターンの照合により、異常を検知します
* 政府のデータベースに (許可されている場合は) リアルタイムで照会し、信頼できる検証を行います> [!NOTE]
>
> *重要な理由*: 包括的なデータ処理により、正確性が確保されてエラーがなくなり、すべての確認に自信を持てます。**3. 高度な分析**AI 搭載のシステムが、包括的なチェックを行います。- 書類の真正性の検証
- 改ざんの検知と画像の完全性の分析
- セキュリティ機能 (ホログラム、透かしなど) の検証
- 認証済みデータベースに対するテンプレートの照合**書類のライブネス検知** は、次のような不正を防ぎます。| 攻撃の種類 | 説明 |
| - | - |
| **画面のキャプチャ** | 画面に表示されたデジタル書類を撮影したもの |
| **画面のリプレイ** | 画面に表示された書類の写真 |
| **印刷されたコピー** | 原本を物理的に複製したもの |
| **顔写真の改ざん** | 顔写真を差し替えたり編集したりした書類 |**4. シームレスな結果と連携**柔軟な提供方法で、すぐに活用できるインサイトを得られます。**リアルタイムの結果**:| チャネル | 説明 |
| - | - |
| **ダッシュボード** | 直感的なダッシュボードで即座に更新を確認できます |
| **Webhook** | 自動化されたワークフロー向けに、即時の Webhook 通知を送信します |
| **REST API** | 既存のシステムにシームレスに統合できます |**包括的なレポート**:* 確認結果と証拠を含む、詳細な PDF レポート
* コンプライアンスと記録の保管のための監査証跡
* 運用上のニーズに合わせられるカスタマイズ可能なオプション> [!NOTE]
>
> *重要な理由*: 迅速でアクセスしやすい結果により、チームは安全で監査可能なプロセスを保ちながら、すばやく対応できます。***## 書類の要件確認を確実に成功させるには、書類が次の基準を満たしている必要があります。#### 一般的な要件- 政府が発行したもので、設定された有効期間内であること
- 物理的に損傷がないこと (傷、汚れ、破損により詳細が隠れていないこと)
- すべての重要な情報 (氏名、生年月日、MRZ など) がはっきりと判読できること
- 提出されたすべての書類で、データが一貫していること#### 画像の要件- 原本をリアルタイムで撮影した写真であること (スクリーンショット、スキャン、デジタルコピーは不可)
- 対応フォーマット: JPG、JPEG、PNG、PDF
- 最大ファイルサイズ: 5MB
- 書類の四隅がすべて写っているフルカラーの画像であること
- 反射、影、デジタル編集、加工がないこと
- 物理的な書類が必要です (デジタル ID は、公式に認められている一部の地域でのみ対応します)## 国と書類の種類ごとの追加設定コンソールから直接、国と書類の種類ごとに細かいルールを設定できます。これらのコントロールにより、受け入れ基準と文字表記の設定を、コンプライアンスのニーズに合わせて調整できます。![類似度のしきい値と受け入れルールを設定する、Didit の顔照合の詳細設定パネル](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-additional-settings.jpeg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4238b10a404795a61926fbdf1a3adc20)* **有効期限モード**: 有効期限が過ぎた書類の扱い方を選択します。
  * **期限切れを拒否**: 書類の有効期限が今日より前の場合、期限切れとしてマークして拒否します。
  * **期限切れを許可**: 有効期限が過ぎた書類にフラグを立てたりブロックしたりしません。
* **優先する文字形式**: 抽出された氏名や項目を、どのように正規化するかを選択します。
  * **ラテン文字 (A-Z) を優先**: 例: "Mohammed"
  * **原語の文字 (非ラテン文字) を優先**: 例: "محمد"
* **地域別の対応とサブタイプ**: 地域ごとに書類を有効にし、書類の種類に多くのバリエーションがある場合は、受け入れ可能なサブタイプを指定します。
  * 例: 米国の運転免許証では、受け入れる正確なサブタイプ (たとえば、アリゾナ州の商用運転免許証、インディアナ州の運転免許証 (REAL ID)、ニューヨーク州の強化運転免許証など) を選択します。
  * 「受け入れるサブタイプ」のコントロールを使うと、多数のバリエーション (たとえば「128件選択済み」) をまとめて含めたり除外したりできます。> ヒント: これらの設定は国と書類の種類ごとに適用されるため、市場によっては厳格に、他の市場では柔軟に運用できます。


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