> ## 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：1:N顔照合による重複検出と不正グループ検知 > DiditのPOST /v3/face-search/は、認証済みユーザー全体を対象とする1:N顔検索API。重複アカウント、不正グループの検出や再認証に対応。推論は2秒未満、従量課金で契約不要。 ## OpenAPI ````yaml ja/openapi-25.json POST /v3/face-search/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: 本人確認API。x-api-keyヘッダーで認証します。 servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-search/: post: tags: - Standalone APIs summary: 顔検索 description: >- アプリケーションの顔検索インデックス（認証セッションから登録された顔、保存されたスタンドアロンのAPI呼び出し、ユーザープロフィールへ直接アップロードされた顔、ブロックリストと許可リスト）に対して顔画像を検索（1:N）し、類似度順に並んだ一致結果と、ブロックリストおよび重複に関する警告を取得します。 **仕組み** `user_image`内で検出された最も大きな顔がエンベディング化され、アプリケーションの範囲内でインデックスに対して検索されます。類似度の下限を上回る一致が最大**5件**、`matches`で返されます。各一致には`similarity_percentage`、元のセッション（`session_id`、`session_number`、`status`、`vendor_data`）、そのセッションの書類認証中に抽出された`user_details`、`is_blocklisted` / `is_allowlisted`フラグ、および`source`の識別子（`session`、`imported`、または`list_entry`）が含まれます。 - `search_type=most_similar`（デフォルト）は、登録されたすべての顔を類似度順に並べます。重複排除や不正グループの調査に使用してください。 - `search_type=blocklisted_or_approved`は、候補をブロックリストの顔、許可リストの顔、承認済みセッションの顔、インポートされたユーザープロフィールの顔に限定し、ブロックリストのエントリーを最上位に並べます。ブロックリストのスクリーニングが主な目的の場合に使用してください。 `status`が`Declined`になるのは、`FACE_IN_BLOCKLIST`または`POSSIBLE_FACE_IN_BLOCKLIST`の警告が発生した場合のみです。`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`（`information`）と`MULTIPLE_FACES_DETECTED`（`warning`）によって却下されることはありません。Passive Livenessとは異なり、このエンドポイントは同じ`vendor_data`を持つ過去のセッションを照合対象から除外**しません**。パッシブライブネス分析も内部で実行され、保存されたセッションとともに記録されますが、その結果はこのレスポンスには含まれません。 **請求** `200`レスポンスごとに顔検索APIクレジットを1つ消費します（プランのクレジットまたはチャージ残高から支払われます）。残高が不足している場合は、画像処理の前に`403`が返されます。 **セッションの保存と顔の登録（`save_api_request`、デフォルトは`true`）** `true`の場合、呼び出しはAPIタイプのセッションとして保存され（Business Console、返された`request_id`を使用した`GET /v3/session/{sessionId}/decision/`、`status.updated` Webhook）、検索された顔は顔検索インデックスに登録されます。顔検索の呼び出しによって登録された顔は以降の顔検索結果から除外されるため、繰り返し検索しても互いに一致することはありません。`false`の場合、呼び出しは1回限りです。何も保存されず、顔は登録されず、`match_image_url`の値はダウンロード可能なURLではなく内部ストレージのパスになります。 **サンドボックス** サンドボックスのAPIキーでは、すべての処理と請求がスキップされます。リクエストの検証後（不正な入力には引き続き`400`が返されます）、エンドポイントは静的な`Approved`のモックペイロードを返し、セッションは保存されず、クレジットも消費されません。 **認証** アプリケーションのAPIキーを`x-api-key`ヘッダーで送信してください。認証情報がない場合や無効な場合は`403`（`{"detail": "You do not have permission to perform this action."}`）が返されます。このAPIが`401`を返すことはありません。 **レート制限** すべてのPOST/PATCH/DELETEエンドポイントで共有される書き込み枠として、APIキーごとに毎分300リクエストまでです。超過すると`429`が返されます。 operationId: post_v3face-search parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- 検索に使用する正面を向いた顔画像。使用可能な拡張子: `tiff`、`jpg`、`jpeg`、`png`、`webp`。最大アップロードサイズ: **5 MB**（これを超えるファイルは`400`で拒否されます）。画像は処理前に自動的に約0.5 MBに圧縮されるため、解像度を非常に高くしても精度は向上しません。画像には検出可能な顔が少なくとも1つ含まれている必要があり、含まれていない場合はエンドポイントが`400`を返します。複数の顔が含まれる場合は最も大きい顔が検索され、`MULTIPLE_FACES_DETECTED`警告が追加されます。 search_type: type: string default: most_similar enum: - most_similar - blocklisted_or_approved description: >- 検索ポリシー。`most_similar`（デフォルト）は、アプリケーションに登録されているすべての顔を類似度順にランク付けします。`blocklisted_or_approved`は、候補をブロックリストに登録された顔、許可リストに登録された顔、承認済みセッションの顔、インポートされたユーザープロファイルの顔に限定し、ブロックリストのエントリーを最上位にランク付けします。 example: most_similar rotate_image: type: boolean default: false description: >- `true`の場合、入力を90度ずつ回転させて試し、最も良好に顔を検出できる向きを使用します。EXIFの向き情報がない場合に便利です。レイテンシが増加します。 example: false save_api_request: type: boolean default: true description: >- `true`（デフォルト）の場合、呼び出しをAPIタイプのセッションとして保存し、`status.updated`Webhookを送信し、`match_image_url`の値に署名付きURLを発行し、検索した顔を顔検索インデックスに登録します（顔検索による登録は、以降の検索の対象から除外されます）。`false`の場合、検索は1回限りで、セッションは保存されず、顔も登録されません。 example: true vendor_data: type: string description: >- 任意の不透明な識別子（ユーザーID、メールアドレス、UUIDなど）です。保存されたセッションに格納され、そのまま返されます。検索結果から同一ユーザーの顔が除外されることはありません。 example: user-123 metadata: type: object additionalProperties: true description: >- セッションとともに保存され（`save_api_request=true`の場合）、そのまま返される任意のJSONオブジェクトです。マルチパートリクエストでは、JSONエンコードされた文字列フィールドとして送信してください。オブジェクトとして解析されます。 example: flow: dedup_check example: user_image: (binary JPEG/PNG selfie) search_type: most_similar rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: dedup_check responses: '200': description: >- 顔検索が完了しました。`face_search.matches`には、類似した顔が類似度の高い順に最大5件含まれます。空の配列は、登録済みの顔のいずれも類似度の下限を超えなかったことを意味します。`status`が`Declined`になるのはブロックリストに一致した場合のみです。重複の一致だけでは`Approved`が返されるため、`status`だけでなく`matches`と`warnings`を確認してください。`save_api_request=true`の場合、`request_id`は保存されたセッションIDです。各一致には`source`（`session`、`imported`、`list_entry`、または`retained_template`）、`vendor_user_id`、`biometric_template_id`が含まれます。`retained_template`の一致は、元のセッションが削除された後に保持された画像を含まない生体認証テンプレートに由来するもので、セッションのフィールド、`match_image_url`、`user_details`は`null`になります。 content: application/json: examples: Blocklist hit (Declined): summary: 顔がブロックリストに登録された顔と一致しています value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef face_search: status: Declined total_matches: 1 matches: - session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 session_number: 323442 similarity_percentage: 99.99 source: session vendor_data: user-1 verification_date: '2025-01-01T00:00:00Z' user_details: full_name: Jane Marie Doe document_type: ID document_number: X1234567 match_image_url: https:///face/3f6a1c2e/reference.jpg status: Approved is_blocklisted: true is_allowlisted: false api_service: null vendor_user_id: 2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f biometric_template_id: null user_image: entities: - bbox: - 40 - 40 - 120 - 120 confidence: 0.732973 best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 323442 api_service: null log_type: error short_description: Face in blocklist long_description: >- The system identified a face in the blocklist, which means the face is not allowed to be verified. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Duplicate found (Approved): summary: この顔は別の承認済みセッションですでに検出されています。情報提供のみで、却下にはなりません value: request_id: 5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f face_search: status: Approved total_matches: 1 matches: - session_id: 1f2e3d4c-5b6a-7980-1122-334455667788 session_number: 1024 similarity_percentage: 87.42 source: session vendor_data: user-9 verification_date: '2025-11-20T09:15:00Z' user_details: null match_image_url: https:///face/9c8b7a6d/reference.jpg status: Approved is_blocklisted: false is_allowlisted: false api_service: PASSIVE_LIVENESS vendor_user_id: 2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f biometric_template_id: 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: 1f2e3d4c-5b6a-7980-1122-334455667788 duplicated_session_number: 1024 api_service: PASSIVE_LIVENESS 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' No matches (Approved): summary: 類似度の下限を超える登録済みの顔はありませんでした value: request_id: 9d8c7b6a-5f4e-3d2c-1b0a-998877665544 face_search: status: Approved total_matches: 0 matches: [] user_image: entities: - bbox: - 40 - 40 - 120 - 120 confidence: 0.732973 best_angle: 0 warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- `save_api_request=true`の場合は保存されたセッションID(`GET /v3/session/{sessionId}/decision/`で使用可能)、それ以外の場合は一時的な相関UUIDです。 face_search: type: object properties: status: type: string enum: - Approved - Declined description: >- `FACE_IN_BLOCKLIST`または`POSSIBLE_FACE_IN_BLOCKLIST`の警告が発生した場合にのみ`Declined`になります。重複一致や複数の顔に関する警告によって却下されることはありません。 total_matches: type: integer description: '`matches`内のエントリー数（0–5）。' example: 1 matches: type: array maxItems: 5 description: >- 顔検索インデックスに登録された顔のうち、類似度の下限を超えるものを最大5件、類似度順に返します（`search_type=blocklisted_or_approved`の場合はブロックリストのエントリが先頭に並びます）。十分に類似した登録済みの顔がない場合は空です。 items: type: object properties: session_id: type: string format: uuid nullable: true description: >- 一致した顔が属する検証セッションのID。`source`が`imported`、`list_entry`、`retained_template`のいずれかの場合は`null`です。 example: 882c42d5-8a4d-4d20-8080-a22f57822c86 session_number: type: integer nullable: true description: >- Business Consoleに表示されるわかりやすいセッション番号。セッション以外の一致では`null`です。 example: 323442 similarity_percentage: type: number format: float minimum: 0 maximum: 100 description: 送信された顔と一致した顔の類似度(0〜100)。 example: 99.99 source: type: string enum: - session - imported - list_entry - retained_template description: >- 一致した顔の登録元です。`session`は検証セッションまたは保存されたスタンドアロンのAPI呼び出し、`imported`はユーザープロフィールに直接アップロードされた顔、`list_entry`はいずれかのリストに添付された顔、`retained_template`はユーザーに保存された画像を含まない生体認証テンプレートで、`/v3/biometric-templates/`に一覧表示されます。 vendor_data: type: string nullable: true description: >- 一致したセッション、またはインポートされた顔および保持されたテンプレートの顔の場合は紐付けられたユーザーの`vendor_data`です。 example: user-1 vendor_user_id: type: string format: uuid nullable: true description: >- リンクされたユーザーのID。リストエントリおよびユーザーのないセッションの一致の場合は`null`。 example: 2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4 biometric_template_id: type: string format: uuid nullable: true description: >- 保持された生体認証テンプレートのID。`source`が`retained_template`の場合のみ設定され、それ以外の場合は`null`です。 example: null verification_date: type: string format: date-time nullable: true description: >- 一致した顔が最初に撮影された日時、または保持されたテンプレートが作成された日時（`YYYY-MM-DDThh:mm:ssZ`）。`list_entry`の一致では`null`です。 example: '2025-01-01T00:00:00Z' user_details: type: object nullable: true description: >- 一致したセッションの書類検証で抽出された本人データ。一致したセッションに書類データがない場合(ライブネスのみのセッションなど)は`null`となり、`retained_template`の一致では常に`null`です。`source: imported`の一致では、代わりにユーザープロフィールから値が設定されます: `full_name`は設定され、`document_type`/`document_number`はnullです。 properties: full_name: type: string nullable: true example: Jane Marie Doe document_type: type: string nullable: true example: ID document_number: type: string nullable: true example: X1234567 match_image_url: type: string nullable: true description: >- `save_api_request=true`の場合、一致した顔の参照画像の期限付きURL(`https:///...`)です。`save_api_request=false`の場合は内部ストレージのパスとなり、直接ダウンロードすることはできません。保持されたテンプレートには画像が含まれないため、`retained_template`の一致では常に`null`です。 example: https:///face/3f6a1c2e/reference.jpg status: type: string nullable: true description: >- 一致したセッションのステータス（`Approved`、`Declined`、`In Review`など）。`imported`/`list_entry`の一致では`null`です。 example: Approved is_blocklisted: type: boolean description: >- 一致した顔が顔のブロックリストに登録されている場合は`true`です。十分に類似したブロックリスト上の一致が1件でもあれば、検索は却下されます。 is_allowlisted: type: boolean description: >- 一致した顔がいずれかの許可リストに登録されている場合は`true`です。許可リストに登録された一致では、重複の警告が抑制されます。 api_service: type: string nullable: true description: >- 照合された顔がスタンドアロンのAPI呼び出し（例：`PASSIVE_LIVENESS`）で登録された場合に設定されます。通常の認証セッションおよびインポートされた顔では`null`です。 example: null user_image: type: object description: 送信された画像の顔検出結果。ここでのエントリには`bbox`と`confidence`のみが含まれます。 properties: entities: type: array description: 検出された顔ごとに1エントリー。最も大きい顔が検索対象です。 items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- ピクセル単位のバウンディングボックス`[x_min, y_min, x_max, y_max]`。 example: - 40 - 40 - 120 - 120 confidence: type: number format: float minimum: 0 maximum: 1 description: 顔検出の信頼度（0～1）。 example: 0.732973 best_angle: type: integer description: >- 最も良好な顔検出結果が得られた回転角度(度)。`rotate_image=true`によって向きが補正された場合にのみゼロ以外になります。このエンドポイントではnullになることはありません(モデルが値を省略した場合は0がデフォルトになります)。 example: 0 warnings: type: array description: >- リスクシグナル。`FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`(`error`)は検索を却下します。`MULTIPLE_FACES_DETECTED`(`warning`)と`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`(`information`)は参考情報です。 items: type: object properties: risk: type: string enum: - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: 機械可読なリスクコードです。 feature: type: string enum: - LIVENESS description: 警告を発生させた機能。このエンドポイントでは常に`LIVENESS`です。 additional_data: type: object nullable: true additionalProperties: true description: >- `MULTIPLE_FACES_DETECTED`の場合は`null`。ブロックリストの一致には`{blocklisted_session_id, blocklisted_session_number, api_service}`が含まれ、重複の一致には最初に一致したセッションを指す`{duplicated_session_id, duplicated_session_number, api_service}`が含まれます。 log_type: type: string enum: - error - warning - information description: >- 重大度。`error`の警告は`status`を`Declined`にします。`warning`と`information`のエントリーは参考情報であり、それ単独で却下になることはありません。 short_description: type: string description: リスクを人が読める形で1行にまとめた要約。 long_description: type: string description: リスクを人が読める形で説明したもの。 vendor_data: type: string nullable: true description: 送信した`vendor_data`のエコー、または`null`。 metadata: type: object nullable: true additionalProperties: true description: 送信した`metadata`オブジェクトのエコー、または`null`。 created_at: type: string format: date-time description: >- レスポンスが生成された日時を示すISO 8601タイムスタンプ（UTC）。例: `2026-06-12T01:04:42.763237+00:00`。 '400': description: >- バリデーションエラー。`user_image`がない、5MBを超える、サポートされていない拡張子である、または送信された画像で**顔が検出されない**場合に返されます。フィールドエラーはDRFの`{field: [messages]}`エンベロープを使用し、顔検出の失敗は`{"error": ...}`を使用します。 content: application/json: examples: No face detected: summary: 画像は正常にデコードできますが、検出可能な顔が含まれていません value: error: No face detected in the image Missing image: summary: フォームデータに`user_image`が含まれていません value: user_image: - No file was submitted. Unsupported file extension: summary: ファイル拡張子がtiff/jpg/jpeg/png/webp以外 value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: アップロードが5MBの上限を超えています value: user_image: - File size should not exceed 5 MB '403': description: >- 権限がありません。`x-api-key`ヘッダーがない場合に加え、呼び出し元の組織の残高が呼び出しを賄えない場合にも返されます。誤った、取り消された、または期限切れのキーの場合は`401`が返されます。キーがない場合は`{"detail": ...}`とともに`403`が返され、誤った、取り消された、または期限切れのキーの場合は`401`が返されます。クレジット不足の場合は、画像の処理が行われる前に`{"error": ...}`とともに`403`が返されます。 content: application/json: examples: Missing or invalid API key: summary: '`x-api-key`ヘッダーがないか、キーが無効または失効しています' value: detail: You do not have permission to perform this action. Not enough credits: summary: 組織の残高でこの呼び出しの料金を賄えません value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- レート制限を超過しました。すべてのPOST/PATCH/DELETEエンドポイントは、APIキーごとに1分あたり300件の書き込みリクエストという共通の上限を共有します。レスポンスには`X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`、`Retry-After`ヘッダーが含まれます。 content: application/json: examples: Write rate limit exceeded: summary: 現在の1分間に300件を超える書き込みリクエスト value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-search/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'search_type=most_similar' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_search.search( user_image=open("user_image.jpg", "rb"), search_type="most_similar", rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "dedup_check"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceSearch.search({ user_image: await fileFromPath("user_image.jpg"), search_type: "most_similar", rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "dedup_check" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceSearch.Search(ctx, didit.FaceSearchSearchParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tSearchType: didit.Some(didit.FaceSearchSearchParamsSearchType(\"most_similar\")),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"dedup_check\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceSearchSearchParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceSearch().search(FaceSearchSearchParams.builder() .userImage(Path.of("user_image.jpg")) .searchType(FaceSearchSearchParams.SearchType.of("most_similar")) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "dedup_check")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceSearch->search([ 'user_image' => File::fromPath('user_image.jpg'), 'search_type' => 'most_similar', 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'dedup_check'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_search.search( user_image: Pathname("user_image.jpg"), search_type: "most_similar", rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "dedup_check" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceSearch.SearchAsync(new FaceSearchSearchParams { UserImage = FileUpload.FromPath("user_image.jpg"), SearchType = new FaceSearchSearchParamsSearchType("most_similar"), RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "dedup_check" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権（なし、読み取り、書き込み）、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.