> ## 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（Face Match）：1:1の顔比較 > DiditのFace Match APIは、POST /v3/face-match/で1:1の顔比較を行います。本人確認、アクセス制御、再認証に対応。推論は2秒未満、従量課金制で月額最低料金はありません。 ## OpenAPI ````yaml ja/openapi-25.json POST /v3/face-match/ 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-match/: post: tags: - Standalone APIs summary: 顔照合 description: >- 2枚の顔画像を比較(1:1)し、類似度の`score`(0–100)と`Approved`/`Declined`の`status`を返します。 **仕組み。** 両方の画像をデコードし、生体認証モデルで分析します(撮影画像が横向きや上下逆になる可能性がある場合は`rotate_image=true`を設定してください)。その後、2つの顔の類似度スコアを算出します。スコアが`face_match_score_decline_threshold`(デフォルト`30`)を**厳密に上回る**場合は`status: "Approved"`を返し、しきい値以下の場合は`LOW_FACE_MATCH_SIMILARITY`警告付きで`Declined`を返します。スコアを算出できる顔のペアがまったくない場合でも、呼び出しは`200`を返し、`status: "Declined"`と`NO_REFERENCE_IMAGE`警告が付きます。`score`はデフォルトの保存パスでは`null`、`save_api_request=false`の場合は`0`になります。最良の結果を得るには、各画像に正面を向いた鮮明な顔を1つずつ含めて送信してください。 **請求。** `200`レスポンスごとにFace Match APIクレジットを1つ消費します(プランのクレジットまたはチャージ残高から支払われます)。組織の残高で呼び出しをまかなえない場合、エンドポイントは画像処理を行う前にクレジット不足エラーとともに`403`を返します。 **セッションの永続化(`save_api_request`、デフォルト`true`)。** `true`の場合、呼び出しはAPIタイプのセッションとして永続化されます。Business Consoleに表示され、返される`request_id`は`GET /v3/session/{sessionId}/decision/`に渡せる実際のセッションIDとなり、両方の画像がセッションの顔照合のソース画像/ターゲット画像として保存され、設定済みのWebhookエンドポイントに`status.updated`Webhookが送信されます。`false`の場合は何も保存されず、`request_id`は後から参照できない1回限りの相関用UUIDになります。 **顔検索インデックス。** このエンドポイントは、顔検索インデックスに顔を登録することも、ブロックリストや重複のスクリーニングを実行することもありません。これらには`POST /v3/passive-liveness/`または`POST /v3/face-search/`を使用してください。 **サンドボックス。** サンドボックスの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-match parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image - ref_image properties: user_image: type: string format: binary description: >- 検証するライブまたは候補の顔画像（例：セルフィー）。被写体の顔がはっきりと見え、十分に明るい正面向きの写真を1枚送信してください。使用可能な拡張子：`tiff`、`jpg`、`jpeg`、`png`、`webp`。最大アップロードサイズ：**5 MB**（これより大きいファイルは`400`で拒否されます）。画像は処理前に約0.5 MBへ自動的に圧縮されるため、解像度を非常に高くしても精度は向上しません。 ref_image: type: string format: binary description: >- 比較対象となる基準の顔画像（例: 身分証明書の顔写真や以前に登録した写真）。形式とサイズの制限は`user_image`と同じです。 face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- レスポンスの`status`を決定する類似度のしきい値(0〜100)。算出されたスコアがこの値**以下**の場合、`status`は`Declined`となり、`LOW_FACE_MATCH_SIMILARITY`警告が追加されます。この値を厳密に上回るスコアでは`Approved`が返されます。デフォルトの`30`は緩い設定です。より厳格な検証を行うには値を引き上げてください(例: `50`〜`60`)。0〜100の範囲外の値では`400`が返されます。 example: 50 rotate_image: type: boolean default: false description: >- `true`の場合、入力画像を90度単位（0、90、180、270）で試し、最も良好に顔を検出できる向きを使用します。EXIFの向き情報がないモバイル撮影画像に便利です。レイテンシが増加するため、画像が正立していることを保証できない場合にのみ有効にしてください。 example: false save_api_request: type: boolean default: true description: >- `true`（デフォルト）の場合、呼び出しはAPIタイプのセッションとして保存されます。このセッションはBusiness Consoleに表示され、返された`request_id`を使って`GET /v3/session/{sessionId}/decision/`で取得でき、`status.updated`Webhookで通知されます。`false`の場合、何も保存されず、`request_id`はレスポンスの照合専用の一時的なUUIDになります。 example: true vendor_data: type: string description: >- 任意の不透明な文字列（社内のユーザーID、メールアドレス、UUIDなど）です。保存されたセッションに格納され、レスポンスでそのまま返されます。API呼び出しを自社の記録と関連付けたり、後でセッションを絞り込んだりするために使用します。 example: user-123 metadata: type: object additionalProperties: true description: >- セッションとともに保存され（`save_api_request=true`の場合）、レスポンスでそのまま返される任意のJSONオブジェクトです。マルチパートリクエストでは、JSONエンコードされた文字列フィールドとして送信してください（例: `metadata={"flow":"login"}`）。オブジェクトとして解析されます。 example: flow: login device_id: abc123 example: user_image: (binary JPEG/PNG of the live selfie) ref_image: (binary JPEG/PNG of the reference photo) face_match_score_decline_threshold: 50 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: login responses: '200': description: >- 顔照合の計算が完了しました。`face_match.score`は0～100の浮動小数点数（小数点以下2桁）です。`status`は、スコアが`face_match_score_decline_threshold`を厳密に上回る場合は`Approved`、それ以外の場合は理由を説明する警告付きで`Declined`になります。類似度が低い場合やスコアを算出できないペアでも`200`が返されるため、HTTPコードだけでなく`face_match.status`と`face_match.warnings`を確認してください。`save_api_request=true`の場合、`request_id`は保存されたセッションIDです。 content: application/json: examples: Approved: summary: 同一人物（スコアがしきい値を上回る） value: 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 race: null best_angle: 0 ref_image: entities: - bbox: - 653 - 745 - 1691 - 2185 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: [] vendor_data: user-123 metadata: flow: login created_at: '2026-06-12T01:04:42.763237+00:00' Declined - low similarity: summary: 却下しきい値以下のスコア value: request_id: 7cdda24e-311a-46d3-a3bb-e5d9b564ce73 face_match: status: Declined score: 24.87 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 156 - 234 - 679 - 898 confidence: 0.717775 age: 41.2 gender: male race: null best_angle: 0 warnings: - risk: LOW_FACE_MATCH_SIMILARITY feature: FACEMATCH additional_data: null log_type: error short_description: Low face match similarity long_description: >- The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:08:19.859116+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_match: type: object properties: status: type: string enum: - Approved - Declined description: >- 類似度スコアを算出でき、かつそのスコアが`face_match_score_decline_threshold`を厳密に上回る場合は`Approved`、それ以外は`Declined`です（理由は警告で示されます）。 score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- 0〜100の類似度スコアで、2つの画像が同一人物を写しているというモデルの信頼度を表します。小数点以下2桁に丸められるのは`save_api_request`がtrueの場合のみで、`save_api_request=false`の場合は丸められていない浮動小数点値が返されます。顔のペアをスコアリングできなかった場合は`null`になります(デフォルトの`save_api_request=true`の場合)。`save_api_request=false`の場合、同じ状況が`score: 0`として現れることがあります。いずれの場合も`NO_REFERENCE_IMAGE`警告が含まれ、`status`は`Declined`になります。 example: 99.41 user_image: type: object description: 分析した各画像の顔検出結果。 properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- 処理済み画像内で検出された顔のバウンディングボックス。`[x_min, y_min, x_max, y_max]`のピクセル座標で示します。 example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: 顔検出の信頼度（0～1）。 example: 0.732973 age: type: number format: float description: >- 検出された顔についてモデルが推定した年齢（歳）。参考情報であり、顔照合の判定には影響しません。 example: 26.91 gender: type: string description: >- 検出された顔についてモデルが予測した性別（`male`または`female`）。参考情報です。 example: male race: type: string nullable: true description: 予約済みフィールドです。このエンドポイントのレスポンスでは常に`null`です。 example: null description: 検出された顔ごとに1エントリー。 best_angle: type: integer description: >- 最も良好な顔検出結果が得られた回転角度(度: 0、90、180、270のいずれか)。`rotate_image=true`によって向きが補正された場合にのみゼロ以外になります。 example: 0 ref_image: type: object description: 参照画像の顔検出結果。形式は`user_image`と同じです。 properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- 処理済み画像内で検出された顔のバウンディングボックス。`[x_min, y_min, x_max, y_max]`のピクセル座標で示します。 example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: 顔検出の信頼度（0～1）。 example: 0.732973 age: type: number format: float description: >- 検出された顔についてモデルが推定した年齢（歳）。参考情報であり、顔照合の判定には影響しません。 example: 26.91 gender: type: string description: >- 検出された顔についてモデルが予測した性別（`male`または`female`）。参考情報です。 example: male race: type: string nullable: true description: 予約済みフィールドです。このエンドポイントのレスポンスでは常に`null`です。 example: null description: 検出された顔ごとに1エントリー。 best_angle: type: integer example: 0 warnings: type: array description: >- 問題なく承認された場合は空です。`NO_REFERENCE_IMAGE`（`error`）: スコアリングできる顔のペアがありませんでした。`LOW_FACE_MATCH_SIMILARITY`（`error`）: スコアが却下のしきい値以下です。いずれかが含まれると`status`は`Declined`になります。 items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: 機械可読なリスクコードです。 feature: type: string enum: - FACEMATCH description: 警告を発生させた機能。このエンドポイントでは常に`FACEMATCH`です。 additional_data: type: object nullable: true additionalProperties: true description: 顔照合の警告では常に`null`です。 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: >- バリデーションエラー。必須の画像がない、5MBを超える、サポートされていない拡張子である、またはオプションが範囲外の場合に返されます。ボディはDRFの標準的なフィールドエラーエンベロープで、問題のあるフィールドごとにメッセージの配列が1つ含まれます。 content: application/json: examples: Missing required image: summary: フォームデータに`ref_image`（または`user_image`）が含まれていない value: ref_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 Threshold out of range: summary: '`face_match_score_decline_threshold`が0–100の範囲外です' value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '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-match/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'ref_image=@./id_portrait.jpg' \ -F 'face_match_score_decline_threshold=50' \ -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_match.compare( user_image=open("user_image.jpg", "rb"), ref_image=open("ref_image.jpg", "rb"), face_match_score_decline_threshold=50.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "login"}, ) 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.faceMatch.compare({ user_image: await fileFromPath("user_image.jpg"), ref_image: await fileFromPath("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\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.FaceMatchCompareParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceMatch().compare(FaceMatchCompareParams.builder() .userImage(Path.of("user_image.jpg")) .refImage(Path.of("ref_image.jpg")) .faceMatchScoreDeclineThreshold(50.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "login")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceMatch->compare([ 'user_image' => File::fromPath('user_image.jpg'), 'ref_image' => File::fromPath('ref_image.jpg'), 'face_match_score_decline_threshold' => 50.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'login'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_match.compare( user_image: Pathname("user_image.jpg"), ref_image: Pathname("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" } ) 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.FaceMatch.CompareAsync(new FaceMatchCompareParams { UserImage = FileUpload.FromPath("user_image.jpg"), RefImage = FileUpload.FromPath("ref_image.jpg"), FaceMatchScoreDeclineThreshold = 50.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "login" }, }); 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.