メインコンテンツへスキップ
POST
cURL

承認

x-api-key
string
header
必須

お客様のアプリケーションのAPIキーです。Business ConsoleのDevelopers -> API keysで取得できます。プライマリキーはフルアクセス権を持ちます。名前付きキーにはスコープを設定できます。リソースごとのアクセス権(なし、読み取り、書き込み)、一部のワークフローまたは承認済みセッションへの限定、IPアドレスのリストへの限定、有効期限の設定です。401は、キーが誤っている、失効している、または期限切れであることを意味します。403は、キーが送信されていない、キーにこのリソースやアクションへのアクセス権がない、またはIPリスト外のアドレスからリクエストが送信されたことを意味します。セッションのルートでの404は、セッションがキーのワークフローまたはステータスの対象外であることを意味します。メディアへのアクセス権がないキーでは、画像、動画、PDFのURLがnullで返されます。セッションの書き込み権限がないキーでは、セッションのリンクとトークンがnullで返されます。詳細は次を参照してください: https://docs.didit.me/console/api-keys

ボディ

multipart/form-data
user_image
file
必須

検索に使用する正面を向いた顔画像。使用可能な拡張子: tiff、jpg、jpeg、png、webp。最大アップロードサイズ: 5 MB(これを超えるファイルは400で拒否されます)。画像は処理前に自動的に約0.5 MBに圧縮されるため、解像度を非常に高くしても精度は向上しません。画像には検出可能な顔が少なくとも1つ含まれている必要があり、含まれていない場合はエンドポイントが400を返します。複数の顔が含まれる場合は最も大きい顔が検索され、MULTIPLE_FACES_DETECTED警告が追加されます。

search_type
enum<string>
デフォルト:most_similar

検索ポリシー。most_similar(デフォルト)は、アプリケーションに登録されているすべての顔を類似度順にランク付けします。blocklisted_or_approvedは、候補をブロックリストに登録された顔、許可リストに登録された顔、承認済みセッションの顔、インポートされたユーザープロファイルの顔に限定し、ブロックリストのエントリーを最上位にランク付けします。

利用可能なオプション:
most_similar,
blocklisted_or_approved
例:

"most_similar"

rotate_image
boolean
デフォルト:false

trueの場合、入力を90度ずつ回転させて試し、最も良好に顔を検出できる向きを使用します。EXIFの向き情報がない場合に便利です。レイテンシが増加します。

例:

false

save_api_request
boolean
デフォルト:true

true(デフォルト)の場合、呼び出しをAPIタイプのセッションとして保存し、status.updatedWebhookを送信し、match_image_urlの値に署名付きURLを発行し、検索した顔を顔検索インデックスに登録します(顔検索による登録は、以降の検索の対象から除外されます)。falseの場合、検索は1回限りで、セッションは保存されず、顔も登録されません。

例:

true

vendor_data
string

任意の不透明な識別子(ユーザーID、メールアドレス、UUIDなど)です。保存されたセッションに格納され、そのまま返されます。検索結果から同一ユーザーの顔が除外されることはありません。

例:

"user-123"

metadata
object

セッションとともに保存され(save_api_request=trueの場合)、そのまま返される任意のJSONオブジェクトです。マルチパートリクエストでは、JSONエンコードされた文字列フィールドとして送信してください。オブジェクトとして解析されます。

例:

レスポンス

顔検索が完了しました。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になります。

request_id
string<uuid>

save_api_request=trueの場合は保存されたセッションID(GET /v3/session/{sessionId}/decision/で使用可能)、それ以外の場合は一時的な相関UUIDです。

vendor_data
string | null

送信したvendor_dataのエコー、またはnull。

metadata
object | null

送信したmetadataオブジェクトのエコー、またはnull。

created_at
string<date-time>

レスポンスが生成された日時を示すISO 8601タイムスタンプ(UTC)。例: 2026-06-12T01:04:42.763237+00:00。

最終更新日 2026年11月1日