翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
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 を使用する方法の詳細については、次を参照してください：
