翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
SearchFacesByImage
指定された入力イメージでは、まずイメージ内の最大の顔を検出し、指定したコレクションで一致する顔を検索します。この操作は、入力面のフィーチャを指定されたコレクション内の面と比較します。
入力画像内のすべてのフェースを検索するには、まずIndexFacesオペレーションを呼び出し、それ以降の呼び出しで返される Face 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 です。
Pattern:
[a-zA-Z0-9_.\-]+必須: はい
- FaceMatchThreshold
-
（任意）返されるフェースマッチの最小信頼度を指定します。たとえば、一致の信頼度が 70% 未満の場合は、一致を返さないでください。デフォルト値は 80% です。
Type: 浮動小数点
有効範囲: 最小値は 0 です。最大値は 100 です。
必須: いいえ
- Image
-
base64 でエンコードされたバイトまたは S3 オブジェクトとしての入力イメージ。AWS CLI を使用して Amazon Rekognition オペレーションを呼び出す場合、base64 でエンコードされたイメージのバイトを渡すことはサポートされていません。
AWS SDK を使用して Amazon Rekognition を呼び出す場合は、
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"
},
"Similarity": number
}
],
"FaceModelVersion": "string",
"SearchedFaceBoundingBox": {
"Height": number,
"Left": number,
"Top": number,
"Width": number
},
"SearchedFaceConfidence": number
}レスポンス要素
アクションが成功すると、サービスは HTTP 200 レスポンスを返します。
サービスから以下のデータが JSON 形式で返されます。
- FaceMatches
-
入力面に一致する面の配列と、一致の信頼度です。
Type: の配列FaceMatchobjects
- FaceModelVersion
-
入力コレクションに関連付けられている顔検出モデルのバージョン番号 (
CollectionId).Type: 文字列
- SearchedFaceBoundingBox
-
Amazon Rekognition が検索に使用した、入力画像内の顔の周りのバウンディングボックス。
タイプ: BoundingBox オブジェクト
- SearchedFaceConfidence
-
信頼度
searchedFaceBoundingBoxには、面が含まれています。Type: 浮動小数点
有効範囲: 最小値は 0 です。最大値は 100 です。
Errors
- 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
以下の資料も参照してください。
言語固有の API のいずれかでこの API を使用する方法の詳細については、AWSSDK については、以下を参照してください。
