SearchFacesByImage - Amazon Rekognition

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

SearchFacesByImage

指定された入力イメージでは、まずイメージ内の最大の顔を検出し、指定したコレクションで一致する顔を検索します。この操作では、入力面のフィーチャと、指定したコレクション内の面が比較されます。

注記

入力イメージ内のすべての顔を検索するには、まずIndexFaces操作を行い、その後の呼び出しで返されたフェース ID を使用します。SearchFacesオペレーション.

または、DetectFaces操作し、レスポンスの境界ボックスを使用して顔のクロップを作成します。その後、SearchFacesByImageオペレーション.

入力イメージは、base64 でエンコードされたイメージバイトとして、または Amazon S3 バケット内のイメージへの参照として渡します。AWS CLI を使用して Amazon Rekognition オペレーションを呼び出す場合、イメージのバイトを渡すことはサポートされていません。イメージは PNG または JPEG 形式ファイルにする必要があります。

応答は、一致する面の配列を返します。類似度スコアが一番高い類似度スコアで順に並べられます。具体的には、見つかった各顔の一致のメタデータの配列です。メタデータとともに、レスポンスにはsimilarity面が入力面にどの程度似ているかを示します。レスポンスでは、Amazon Rekognition が入力イメージに使用した顔の境界ボックス (および境界ボックスに顔が含まれている信頼レベル) も返します。

入力イメージで顔が検出されない場合は、SearchFacesByImageを返します。InvalidParameterExceptionというエラーが表示される。

例については、画像を使用して顔を検索する を参照してください。

-QualityFilter入力パラメータを使用すると、必要な品質バーを満たさない検出された顔を除外できます。品質バーは、さまざまな一般的なユースケースに基づいています。を使用するQualityFilterを指定して、フィルタリングの品質バーを設定するにはLOW,MEDIUM, またはHIGH。検出された面をフィルタリングしない場合は、NONE。デフォルト値は NONE です。

注記

品質フィルタリングを使用するには、バージョン 3 以上の顔モデルに関連付けられているコレクションが必要です。コレクションに関連付けられている顔モデルのバージョンを取得するには、DescribeCollection を呼び出します。

このオペレーションには rekognition:SearchFacesByImage アクションを実行するアクセス許可が必要です。

リクエストの構文

{ "CollectionId": "string", "FaceMatchThreshold": number, "Image": { "Bytes": blob, "S3Object": { "Bucket": "string", "Name": "string", "Version": "string" } }, "MaxFaces": number, "QualityFilter": "string" }

リクエストパラメータ

リクエストは以下の JSON 形式のデータを受け入れます。

CollectionId

検索するコレクションの ID。

Type: 文字列

長さの制約: 最小長は 1 です。 最大長は 255 です。

パターン: [a-zA-Z0-9_.\-]+

: 必須 はい

FaceMatchThreshold

(任意)返す面一致の最小信頼度を指定します。たとえば、一致の信頼度が 70% 未満のマッチを返さないでください。デフォルト値は 80% です。

Type: 浮動小数点

有効範囲: 最小値は 0 です。最大値は 100 です。

: 必須 いいえ

Image

base64 でエンコードされたバイトまたは S3 オブジェクトとしての入力イメージ。AWS CLI を使用して Amazon Rekognition オペレーションを呼び出す場合、base64 でエンコードされたイメージのバイトを渡すことはサポートされていません。

AWS SDK を使用して Amazon Rekognition を呼び出す場合は、を使用して渡されたイメージバイトを base64 エンコードする必要がない場合があります。Bytesフィールド。詳細については、「イメージの仕様」を参照してください。

型: Image オブジェクト

: 必須 はい

MaxFaces

返される顔の最大数。この操作は、一致の信頼度が最も高い面の最大数を返します。

Type: 整数

有効範囲: 最小値は 1 です。最大値は 4096 です。

: 必須 いいえ

QualityFilter

面を識別するためのフィルタ処理量を示す品質バーを指定するフィルタ。フィルターされた顔はコレクション内で検索されません。を指定した場合AUTOでは、Amazon Rekognition が品質バーを選択します。を指定した場合LOW,MEDIUM, またはHIGHを選択すると、選択した品質バーを満たさないすべての面がフィルタリングによって削除されます。品質バーは、さまざまな一般的なユースケースに基づいています。品質の低い検出は、さまざまな理由で発生する可能性があります。例としては、顔と誤認される物体、ぼやけすぎた顔、または極端すぎて使用できないポーズを持つ顔などがあります。を指定した場合NONEの場合、フィルタリングは実行されません。デフォルト値は NONE です。

品質フィルタリングを使用するには、バージョン 3 以上の顔モデルに関連付けられているコレクションが必要です。

Type: 文字列

有効な値: NONE | AUTO | LOW | MEDIUM | HIGH

: 必須 いいえ

レスポンスの構文

{ "FaceMatches": [ { "Face": { "BoundingBox": { "Height": number, "Left": number, "Top": number, "Width": number }, "Confidence": number, "ExternalImageId": "string", "FaceId": "string", "ImageId": "string", "IndexFacesModelVersion": "string" }, "Similarity": number } ], "FaceModelVersion": "string", "SearchedFaceBoundingBox": { "Height": number, "Left": number, "Top": number, "Width": number }, "SearchedFaceConfidence": number }

レスポンス要素

アクションが成功すると、サービスは HTTP 200 レスポンスを返します。

サービスから以下のデータが JSON 形式で返されます。

FaceMatches

入力フェースとマッチの信頼度に一致するフェースの配列。

Type: の配列FaceMatchオブジェクト

FaceModelVersion

入力コレクションに関連付けられている顔検出モデルのバージョン番号 (CollectionId).

Type: 文字列

SearchedFaceBoundingBox

Amazon Rekognition が検索に使用した入力イメージの顔の周りの境界ボックス。

型: BoundingBox オブジェクト

SearchedFaceConfidence

という信頼度はsearchedFaceBoundingBox、顔が含まれています。

Type: 浮動小数点

有効範囲: 最小値は 0 です。最大値は 100 です。

エラー

AccessDeniedException

アクションを実行する権限がありません。

HTTP ステータスコード: 400

ImageTooLargeException

入力イメージサイズが制限文字数を超えています。あなたが電話している場合DetectProtectiveEquipmentでは、画像サイズまたは解像度が制限文字数を超えています。詳細については、「Amazon Rekognition のガイドラインとクォータ」を参照してください。

HTTP ステータスコード: 400

InternalServerError

Amazon Rekognition でサービスの問題が発生しました。もう一度やり直してください。

HTTP ステータスコード: 500

InvalidImageFormatException

指定されたイメージ形式はサポートされていません。

HTTP ステータスコード: 400

InvalidParameterException

入力パラメータが制約に違反しています。API オペレーションを再度呼び出す前にパラメータを検証します。

HTTP ステータスコード: 400

InvalidS3ObjectException

Amazon Rekognition は、リクエストで指定された S3 オブジェクトにアクセスできません。

HTTP ステータスコード: 400

ProvisionedThroughputExceededException

お客様のスループット制限を超えたリクエストの数。この上限を引き上げる場合は、Amazon Rekognition までお問い合わせください。

HTTP ステータスコード: 400

ResourceNotFoundException

リクエストで指定されたリソースが見つかりません。

HTTP ステータスコード: 400

ThrottlingException

Amazon Rekognition は一時的にリクエストを処理できませんでした。もう一度やり直してください。

HTTP ステータスコード: 500

以下の資料も参照してください。

言語固有の AWS SDK のいずれかでこの API を使用する方法の詳細については、次を参照してください: