didit-face-match

Didit Face Match API

概要

2 枚の顔画像を比較し、同一人物かどうかを判定します。類似度スコア（0～100）と、Approved / Declined のステータスを返します。

主な制約：

• 許可されるファイル拡張子：tiff、jpg、jpeg、png、webp（PDF は不可）
• ファイルサイズの上限：画像 1 枚あたり 5 MB（処理前に画像は約 0.5 MB に圧縮されます）
• user_image と ref_image は両方とも必須です
• 最良の結果を得るため、各画像には正面を向いた、明瞭で十分な明るさの顔を 1 人分だけ含めてください

料金：$0.05（呼び出し成功 1 回あたり。単独での呼び出しに無料枠はありません）。Didit の料金体系が変更され、月 500 回の無料チェックが月 $10 分の無料クレジットになる 2026 年 11 月 1 日までは、こちらの通常価格が適用されます。最新の料金は didit.me/pricing をご確認ください。

判定：スコアが face_match_score_decline_threshold（デフォルトは 30）を厳密に上回る場合にのみ Approved となります。この値以下のスコアの場合、LOW_FACE_MATCH_SIMILARITY とともに Declined が返されます。スコアを算出できる顔のペアがない場合でも、HTTP 200 と Declined、NO_REFERENCE_IMAGE が返されます。このエンドポイントに In Review はありません。設定できるのはしきい値のみです。

顔検索インデックス：このエンドポイントでは、顔の登録やブロックリストのチェック、重複スクリーニングは一切行いません。これらには POST /v3/passive-liveness/（didit-liveness-detection）または POST /v3/face-search/（didit-face-search）を使用してください。

**保存（save_api_request、デフォルトは true）：**呼び出しは API セッションとして保存されます（Business Console、GET /v3/session/{request_id}/decision/、status.updated webhook）。また、両方の画像がセッションの顔照合元画像および対象画像として保存されます。false の場合は何も保存されず、request_id を使った検索もできません。

**サンドボックス：**サンドボックス API キーでは、リクエストの検証後に固定の Approved ペイロードが返されます。保存や課金は行われません。

**機能：**類似度のスコアリング、設定可能な却下しきい値、顔ごとの顔のバウンディングボックスとモデル推定の年齢・性別（参考情報）、正立していない顔の任意の回転。

API リファレンス： https://docs.didit.me/standalone-apis/face-match 機能ガイド： https://docs.didit.me/core-technology/face-match/overview

---

認証

すべてのリクエストには x-api-key ヘッダーが必要です。Didit Business Console の Developers > API keys からアプリケーションの API キーを使用するか、アカウントとキーをプログラムから作成してください（「Getting Started」を参照）。カスタムアクセス権を設定した名前付きキーで単独チェックを実行するには、Sessions の書き込み権限が必要です。一部のワークフローまたは承認済みセッションのみに制限されたキーでは実行できません。

はじめに（アカウントをお持ちでない場合）

Didit API キーをお持ちでない場合は、2 回の API 呼び出しで作成できます。

1. 登録： POST https://apx.didit.me/auth/v2/programmatic/register/ に {"email": "[email protected]", "password": "MyStr0ng!Pass"} を送信します
2. メールを確認し、6 文字の確認コードを取得します
3. 確認： POST https://apx.didit.me/auth/v2/programmatic/verify-email/ に {"email": "[email protected]", "code": "A3K9F2"} を送信します。キーはレスポンスの application.api_key に含まれます。

**クレジットの追加：**残高の確認には GET /v3/billing/balance/ を使用します。Stripe のチェックアウトリンクを取得するには、{"amount_in_dollars": 50} を指定して POST /v3/billing/top-up/ を呼び出します。

プラットフォーム管理（ワークフロー、セッション、ユーザー、請求）の詳細は、didit-verification-management スキルをご覧ください。

---

エンドポイント

POST https://verification.didit.me/v3/face-match/

ヘッダー

ヘッダー	値	必須
x-api-key	API キー	はい
Content-Type	multipart/form-data（HTTP クライアントによって設定）	はい

リクエストパラメーター（multipart/form-data）

パラメーター	型	必須	デフォルト	制約	説明
user_image	file	はい	-	tiff/jpg/jpeg/png/webp、最大 5 MB	照合する顔（例：自撮り写真）
ref_image	file	はい	-	上記と同じ	参照する顔（例：身分証明書の顔写真、または登録済みの写真）
face_match_score_decline_threshold	float	いいえ	30	0-100	スコアがこの値以下の場合は LOW_FACE_MATCH_SIMILARITY で否認されます。この値を厳密に上回る場合は承認されます
rotate_image	boolean	いいえ	false	-	両方の画像を 0/90/180/270 度で試し、顔検出の結果が最も良い向きを使用します。レイテンシーが増加します
save_api_request	boolean	いいえ	true	-	API セッションとして保存し、両方の画像を保存します（概要を参照）
vendor_data	string	いいえ	-	-	ユーザー識別子。保存され、レスポンスで返されます
metadata	JSON object	いいえ	-	multipart 内では JSON エンコードされた文字列	セッションとともに保存され（保存する場合）、レスポンスで返されます

例

import requests

with open("selfie.jpg", "rb") as selfie, open("id_photo.jpg", "rb") as portrait:
    response = requests.post(
        "https://verification.didit.me/v3/face-match/",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={
            "user_image": ("selfie.jpg", selfie, "image/jpeg"),
            "ref_image": ("id_photo.jpg", portrait, "image/jpeg"),
        },
        data={"face_match_score_decline_threshold": "50", "vendor_data": "user-123"},
        timeout=60,
    )
response.raise_for_status()
face_match = response.json()["face_match"]
print(face_match["status"], face_match["score"])

const formData = new FormData();
formData.append("user_image", selfieFile);
formData.append("ref_image", referenceFile);
formData.append("face_match_score_decline_threshold", "50");
formData.append("vendor_data", "user-123");

const response = await fetch("https://verification.didit.me/v3/face-match/", {
  method: "POST",
  headers: { "x-api-key": "YOUR_API_KEY" },
  body: formData,
});
const { face_match } = await response.json();

レスポンス（200 OK）

{
  "request_id": "f9f5a777-8002-44c6-baaf-128bcfd6e226",
  "face_match": {
    "status": "Approved",
    "score": 99.41,
    "user_image": {
      "entities": [
        {"bbox": [661, 728, 1688, 2188], "confidence": 0.732973, "age": 26.91, "gender": "male"}
      ],
      "best_angle": 0
    },
    "ref_image": {
      "entities": [
        {"bbox": [653, 745, 1691, 2185], "confidence": 0.722082, "age": 27.0, "gender": "male"}
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

ステータス値と処理方法

ステータス	意味	対応
"Approved"	スコアがしきい値を厳密に上回っています	顔が一致しています。次に進んでください
"Declined"	スコアがしきい値以下（LOW_FACE_MATCH_SIMILARITY）、またはスコアを算出できる顔のペアがありません（NO_REFERENCE_IMAGE）	warnings を確認してください。NO_REFERENCE_IMAGE の場合は、より鮮明な画像を求めてください（横向きに撮影された画像では rotate_image=true を試してください）

エラーレスポンス

コード	意味	対応
400	無効なリクエスト（画像がない、ファイルが 5 MB を超えている、サポートされていない拡張子、しきい値が 0-100 の範囲外）	レスポンス本文のフィールドエラーを確認してください
401	API キーの有効期限が切れています	Developers > API keys でキーをローテーションするか、新しいキーを作成してください
403	API キーがない、誤っている、または取り消されている、このエンドポイントへのアクセス権がないスコープ付きキー、キーの IP 許可リスト外からのリクエスト、またはクレジット不足	detail または error のメッセージを確認してください。x-api-key ヘッダーまたはキーのアクセス権を修正するか、クレジットを追加してください
429	レート制限：キーごとに 1 分あたり POST/PATCH/DELETE リクエストは 300 件、GET リクエストは 600 件	Retry-After の秒数だけ待ってから、再試行してください

---

レスポンスフィールドのリファレンス

フィールド	型	説明
request_id	uuid	save_api_request=true の場合はセッション ID（GET /v3/session/{request_id}/decision/ で使用）。それ以外の場合は一時的な相関 ID
face_match.status	string	"Approved" または "Declined"
face_match.score	float or null	0-100 の類似度（高いほど類似しています）。保存時は小数点以下 2 桁に丸められます。save_api_request=false の場合は生の float です。スコアを算出できる顔のペアがない場合は、null（保存時）または 0（未保存時）になり、常に NO_REFERENCE_IMAGE が付与されます
face_match.user_image.entities[]	array	検出された顔ごとに 1 つのエントリー：bbox [x_min, y_min, x_max, y_max]、confidence（0-1）、age、gender。年齢と性別は参考情報であり、判定には影響しません
face_match.user_image.best_angle	integer	検出結果が最も良かった回転角度（0、90、180、270）。rotate_image=true によって向きが補正された場合にのみ、0 以外になります
face_match.ref_image	object	参照画像の情報。user_image と同じ形式です
face_match.warnings[]	array	{risk, feature, additional_data, log_type, short_description, long_description}。feature は常に FACEMATCH、additional_data は常に null です
vendor_data	string or null	送信した値のエコー
metadata	object or null	送信した値のエコー
created_at	string	レスポンスの ISO 8601 UTC 時刻

---

警告タグ

タグ	重大度	却下	発生条件
NO_REFERENCE_IMAGE	error	はい	スコアを算出できる顔のペアがありません（例：いずれかの画像に使用可能な顔がない）
LOW_FACE_MATCH_SIMILARITY	error	はい	スコアが face_match_score_decline_threshold 以下です

このエンドポイントでは NO_FACE_DETECTED は発生しません。顔が見つからない場合は NO_REFERENCE_IMAGE として通知されます。

セキュリティのベストプラクティス： status、score、request_id のみを保存してください。save_api_request=true の場合、保存された画像はセッションの判定から有効期限付き URL（デフォルトで 4 時間）で取得できるため、生体画像をサーバーに保管する必要はありません。

---

閾値の選択

• デフォルトの 30 は寛容な値です。より厳格な検証を行うには、値を上げてください（例：50～60）。0～100 の範囲外の値を指定すると 400 が返されます。
• 判定は「閾値を厳密に上回る場合に承認」です。閾値が 50 の場合、スコアが 50.0 なら却下されます。
• 単独エンドポイントにあるのは却下の閾値のみです。ホスト型ワークフロー（FACE_MATCH 機能）では、別途 face_match_score_review_threshold が追加され、2 つの閾値の間のスコアは In Review に送られます。
• score を独自の判定結果と併せて記録し、誤一致への許容度に合わせて閾値を調整してください。

---

一般的なワークフロー

自撮り写真と身分証明書の照合

1. POST /v3/passive-liveness/ with the selfie -> confirm it is live (didit-liveness-detection)
2. POST /v3/id-verification/ with the document -> extract and check it (didit-id-document-verification)
3. POST /v3/face-match/ with user_image=selfie, ref_image=document portrait
4. All Approved -> the live person matches the document

1 つのセッションで 3 つの処理すべてを実行するホスト型フローには、OCR、LIVENESS、FACE_MATCH を含むワークフローを使用してください（didit-kyc-onboarding スキルを参照）。

---

ユーティリティスクリプト

export DIDIT_API_KEY="your_api_key"

python scripts/match_faces.py selfie.jpg id_photo.jpg
python scripts/match_faces.py selfie.jpg id_photo.jpg --threshold 50 --rotate --vendor-data user-123
python scripts/match_faces.py selfie.jpg id_photo.jpg --no-save --metadata '{"flow": "login"}'