didit-face-search

Didit Face Search API（1:N）

概要

画像内の最も大きな顔をアプリケーションの顔検索インデックスと照合し、類似度のしきい値を上回る上位5件までの一致候補と、ブロックリストおよび重複に関する警告を返します。

検索対象： ステータスを問わず検証セッションから登録された顔、保存された単独の API 呼び出し（例：save_api_request=true を指定した Passive Liveness や Age Estimation）、User プロフィールに直接アップロードされた顔、リスト（ブロックリスト、許可リスト）上の顔、User に保持するよう選択した画像を含まない生体認証テンプレートが対象です。以前の Face Search 呼び出しで登録された顔は検索結果に含まれないため、繰り返し検索しても互いに一致しません。

検索モード（search_type）：

• most_similar（デフォルト）：登録されたすべての顔を類似度順に並べます。重複検出や不正グループの調査に使用します。
• blocklisted_or_approved：ブロックリスト上の顔、許可リスト上の顔、承認済みセッションの顔、インポートされた User の顔、保持されたテンプレートのみを対象とし、ブロックリストの項目を上位に並べます。ブロックリストのスクリーニングに使用します。

主な制約：

• 使用できるファイル拡張子：tiff、jpg、jpeg、png、webp（PDF は不可）
• 最大ファイルサイズ：5 MB（処理前に画像を約 0.5 MB に圧縮します）
• 画像内に検出可能な顔が含まれている必要があります。含まれていない場合、HTTP 400 {"error": "No face detected in the image"} が返されます
• 複数の顔がある場合は最も大きな顔が検索され、MULTIPLE_FACES_DETECTED が追加されます
• vendor_data は、同じユーザーの以前の顔を検索結果から除外しません（Passive Liveness とは異なります）

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

判定： FACE_IN_BLOCKLIST または POSSIBLE_FACE_IN_BLOCKLIST が発生した場合に限り Declined となり、それ以外は Approved です。重複や複数顔の警告によって却下されることはなく、In Review もありません。Approved は顔が新しいことを意味するものではありません。total_matches と重複に関する警告を確認してください。このエンドポイントは生体検知の判定を返しません（生体検知には didit-liveness-detection を使用してください）。

保存と登録（save_api_request、デフォルトは true）： 呼び出しは API セッションとして保存されます（Business Console、GET /v3/session/{request_id}/decision/、status.updated webhook）。match_image_url の値は署名付き URL で、検索した顔はインデックスに登録されます（ただし、後続の検索結果には返されません）。false の場合は何も保存されず、顔も登録されません。また、match_image_url の値はダウンロードできない内部ストレージパスになります。

類似度の目安： Face Search のドキュメントでは、90% 以上は同一人物である可能性が高く、70～89% は確認が必要な場合がある一致候補とされています。Didit 独自の判定は警告に示されます。強い一致では DUPLICATED_FACE / FACE_IN_BLOCKLIST、弱い一致では POSSIBLE_DUPLICATED_FACE / POSSIBLE_FACE_IN_BLOCKLIST が返されます。

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

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

---

認証

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

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

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

1. 登録： {"email": "[email protected]", "password": "MyStr0ng!Pass"} を指定して POST https://apx.didit.me/auth/v2/programmatic/register/ を実行します
2. メールを確認し、6 文字の確認コードを取得します
3. 認証： {"email": "[email protected]", "code": "A3K9F2"} を指定して POST https://apx.didit.me/auth/v2/programmatic/verify-email/ を実行します。キーはレスポンスの 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-search/

ヘッダー

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

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

パラメーター	型	必須	デフォルト	説明
user_image	ファイル	はい	-	検索する顔画像（tiff/jpg/jpeg/png/webp、最大 5 MB）
search_type	文字列	いいえ	most_similar	most_similar または blocklisted_or_approved（概要を参照）
rotate_image	ブール値	いいえ	false	90 度ずつ回転を試し、顔検出の精度が最も高い向きを使用します。遅延が増加します
save_api_request	ブール値	いいえ	true	API セッションとして保存し、検索した顔を登録します（概要を参照）
vendor_data	文字列	いいえ	-	保存され、レスポンスに返されるユーザー ID です。検索結果のフィルターには使用されません
metadata	JSON オブジェクト	いいえ	-	セッションとともに保存され（保存する場合）、レスポンスに返されます。multipart では JSON エンコードした文字列として送信してください

例

import requests

with open("photo.jpg", "rb") as f:
    response = requests.post(
        "https://verification.didit.me/v3/face-search/",
        headers={"x-api-key": "YOUR_API_KEY"},
        files={"user_image": ("photo.jpg", f, "image/jpeg")},
        data={"search_type": "most_similar", "vendor_data": "user-123"},
        timeout=60,
    )
response.raise_for_status()
result = response.json()["face_search"]
for match in result["matches"]:
    print(match["similarity_percentage"], match["source"], match["session_id"], match["is_blocklisted"])

const formData = new FormData();
formData.append("user_image", photoFile);
formData.append("search_type", "most_similar");

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

レスポンス（200 OK）

{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 97.31,
        "source": "session",
        "vendor_data": "user-1",
        "vendor_user_id": "2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4",
        "biometric_template_id": null,
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {"bbox": [40, 40, 120, 120], "confidence": 0.732973}
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "DUPLICATED_FACE",
        "feature": "LIVENESS",
        "additional_data": {
          "duplicated_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "duplicated_session_number": 323442,
          "api_service": null
        },
        "log_type": "information",
        "short_description": "Duplicated face from other approved session",
        "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

ステータス値と対処方法

ステータス	意味	対処方法
"Approved"	ブロックリストへの一致はありません	ユーザーを新規ユーザーとして扱う前に、total_matches と DUPLICATED_FACE / POSSIBLE_DUPLICATED_FACE を確認してください
"Declined"	FACE_IN_BLOCKLIST または POSSIBLE_FACE_IN_BLOCKLIST が発生しました	ブロックするか確認してください。matches[].is_blocklisted と警告の additional_data を参照してください

エラーレスポンス

コード	意味	対処方法
400	リクエストが無効です	レスポンス本文にあるフィールドエラーを確認してください
400	{"error": "No face detected in the image"}	はっきり正面を向いた顔が 1 つ写っている新しい画像を要求してください（または rotate_image=true で再試行してください）
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_search.status	string	"Approved" または "Declined"
face_search.total_matches	integer	matches 内のエントリー数（0～5）
face_search.matches[]	array	類似度順に並んだ最大5件の一致結果（blocklisted_or_approved により、ブロックリスト登録済みのものが先）。十分に類似したものがない場合は空
face_search.user_image.entities[]	array	検出された顔ごとに1件。bbox [x_min, y_min, x_max, y_max] と confidence（0～1）のみを含む
face_search.user_image.best_angle	integer	最適な検出結果が得られた回転角度（度）。rotate_image=true によって補正された場合を除き 0
face_search.warnings[]	array	{risk, feature, additional_data, log_type, short_description, long_description}。feature は常に LIVENESS
vendor_data / metadata	string / object or null	送信した内容のエコー
created_at	string	レスポンスの ISO 8601 UTC 時刻

一致オブジェクト

フィールド	型	説明
similarity_percentage	float	顔と一致した顔の類似度（0～100）
source	string	session（認証セッションまたは保存済みの単独呼び出し）、imported（User プロファイルにアップロードされた顔）、list_entry（リストに登録された顔）、retained_template（画像を含まない保持テンプレート。/v3/biometric-templates/ を参照）
session_id	uuid or null	一致したセッション。imported と retained_template の場合は null。list_entry の場合は、該当エントリーの取得元セッションがあればその ID
session_number	integer or null	Business Console に表示されるセッション番号。session_id と同じ規則
vendor_data	string or null	一致したセッションの vendor_data。imported / retained_template の場合は、関連付けられた User の vendor_data
vendor_user_id	uuid or null	関連付けられた User ID。リストのエントリーおよび User のいないセッションでは null
biometric_template_id	uuid or null	retained_template の場合のみ設定
verification_date	string or null	一致した顔が撮影された日時（YYYY-MM-DDThh:mm:ssZ）。list_entry の場合は null
user_details	object or null	一致したセッションの書類認証から取得した {full_name, document_type, document_number}。imported の一致結果には full_name のみが含まれます。本人確認情報がない場合（例：生体検知のみのセッション）および retained_template の場合は null
match_image_url	string or null	save_api_request=true の場合、一致した顔の有効期限付き URL（デフォルトで4時間）。false の場合は内部ストレージパス。retained_template の場合は null
status	string or null	一致したセッションのステータス（Approved、Declined、In Review など）。セッション以外との一致では null
is_blocklisted	boolean	一致した顔が顔ブロックリストに登録されているかどうか
is_allowlisted	boolean	一致した顔が許可リストのいずれかに登録されているかどうか。許可リストに登録された一致結果では、重複に関する警告は抑制されます
api_service	string or null	一致した顔が単独の API 呼び出し（例：PASSIVE_LIVENESS）から取得された場合に設定

警告タグ

タグ	重大度	拒否	発生条件
FACE_IN_BLOCKLIST	error	はい	ブロックリストに登録された顔との強い一致です。additional_data には blocklisted_session_id、blocklisted_session_number、api_service が含まれます
POSSIBLE_FACE_IN_BLOCKLIST	error	はい	ブロックリストに登録された顔との弱い一致です
MULTIPLE_FACES_DETECTED	warning	いいえ	顔が複数検出されました。最も大きい顔が検索されました
DUPLICATED_FACE	information	いいえ	承認済みセッション、インポートされた顔、または保持されたテンプレートの顔との強い一致です。FACE_IN_BLOCKLIST が発生した場合は通知されません。additional_data には duplicated_session_id、duplicated_session_number、api_service が含まれます
POSSIBLE_DUPLICATED_FACE	information	いいえ	同種の弱い一致です。POSSIBLE_FACE_IN_BLOCKLIST が発生した場合は通知されません

• NO_FACE_DETECTED 警告はありません。顔のない画像は HTTP 400 を返します。
• 判定には status、warnings[].risk、matches[] を使用し、各警告に反映される log_type は参考情報として扱ってください。
• 顔のブロックリストと許可リストは Lists API で管理してください（didit-verification-management を参照）。

---

一般的なワークフロー

重複アカウントの検出

1. New user signs up -> POST /v3/face-search/ with the selfie (search_type=most_similar)
2. status "Declined" -> blocklisted face: reject or send to manual review
3. DUPLICATED_FACE / POSSIBLE_DUPLICATED_FACE -> the face already passed on another account:
   compare matches[].vendor_data / vendor_user_id with the current user, then investigate
4. total_matches == 0 -> no similar face is enrolled

ブロックリストの照合のみ

1. POST /v3/face-search/ with search_type=blocklisted_or_approved
2. "Declined" -> blocklist hit (matches[] lists blocklisted entries first)

本人確認と重複検出の組み合わせ

1. POST /v3/face-search/ -> check for existing accounts (run it BEFORE any call that saves this selfie)
2. POST /v3/passive-liveness/ -> verify the user is live (also enrolls the face when saved)
3. POST /v3/id-verification/ -> verify the identity document
4. POST /v3/face-match/ -> compare the selfie to the document portrait
5. All Approved and no duplicate warning -> verified, unique, real user

最初に検索を実行してください。Passive Liveness または Age Estimation によってすでに保存されたセルフィーはインデックスに含まれており、ほぼ100％一致する結果として返されます。その api_service には、単独で使用された API の名前（例：PASSIVE_LIVENESS）が設定されます。

セキュリティ： 一致画像の URL は、デフォルトで4時間後に有効期限が切れます。保存するのは request_id、session_id、similarity_percentage のみとし、生体画像を自社サーバーに保管しないでください。

---

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

search_faces.py：コマンドラインから一致する顔を検索します。

# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"
python scripts/search_faces.py selfie.jpg
python scripts/search_faces.py photo.png --search-type blocklisted_or_approved
python scripts/search_faces.py photo.png --rotate --vendor-data user-123 --no-save