翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
IndexFaces
入力イメージの顔を検出し、指定したコレクションに追加します。
Amazon Rekognition では、検出された実際の顔は保存されません。代わりに、基になる検出アルゴリズムで、最初に入力イメージ内の顔を検出します。アルゴリズムは、顔ごとに、特徴を特徴ベクトルに抽出し、バックエンドデータベースに保存します。Amazon Rekognition は、SearchFacesそしてSearchFacesByImageオペレーション。
詳細については、「コレクションへの顔の追加」を参照してください。
コレクション内の顔の数を取得するには、を呼び出します。DescribeCollection。
顔検出モデルのバージョン 1.0 を使用している場合は、IndexFaces
入力イメージ内の最大の 15 のフェースをインデックスします。これ以降のバージョンの顔検出モデルでは、入力イメージ内の 100 の大きい顔にインデックスを付けることができます。
バージョン 4 以降の顔モデルを使用している場合、イメージの方向情報はOrientationCorrection
フィールド。
使用しているモデルのバージョンを確認するには、DescribeCollectionを選択し、コレクション ID を指定します。また、の値からモデルバージョンを取得することもできます。FaceModelVersion
からのレスポンスの中IndexFaces
詳細については、「モデルのバージョニング」を参照してください。
オプションを指定した場合ExternalImageId
指定した入力イメージについて、Amazon Rekognition はこの ID を検出したすべての顔に関連付けます。あなたが電話したときListFacesオペレーションの場合、応答は外部 ID を返します。この外部イメージ ID を使用して、クライアント側のインデックスを作成し、顔と各イメージに関連付けることができます。次に、インデックスを使用して、イメージ内のすべての顔を検索できます。
を使用して、インデックスを付ける顔の最大数を指定できます。MaxFaces
入力パラメータ。この機能は、イメージ内の最も大きい顔にインデックスを付け、背景に立っている人の顔など、小さい顔にインデックスを付けない場合に役立ちます。
-QualityFilter
入力パラメータを使用すると、必要な品質バーを満たさない検出された顔を除外できます。品質バーは、さまざまな一般的なユースケースに基づいています。デフォルトでは、IndexFaces
は、顔にフィルタを適用するために使用する品質基準を選択します。また、明示的に品質基準を選択することもできます。を使用するQualityFilter
をクリックし、指定して品質バーを設定します。LOW
,MEDIUM
, またはHIGH
。検出された面をフィルタリングしない場合は、NONE
。
品質フィルタリングを使用するには、バージョン 3 以上の顔モデルに関連付けられているコレクションが必要です。コレクションに関連付けられている顔モデルのバージョンを取得するには、DescribeCollection を呼び出します。
は、インデックスが付けられていないイメージ内で検出された顔に関する情報が配列で返されます。UnindexedFaceオブジェクト、UnindexedFaces
。次のような理由により、顔はインデックス付けされません。
-
検出された顔の数が、
MaxFaces
リクエストパラメータ。 -
イメージサイズに比べて顔が小さすぎる。
-
顔が極端にぼやけている。
-
イメージが暗すぎる。
-
顔が極端なポーズをしている。
-
顔に、顔検索に適したディテールがない。
これに応えて、IndexFaces
operation は、検出されたすべての顔のメタデータの配列を返します。FaceRecords
。これには以下が含まれます。
-
境界ボックスは、
BoundingBox
検出された顔の。 -
信頼値、
Confidence
は、境界ボックス内に顔が含まれている信頼度を示します。 -
顔ID、
FaceId
は、検出されて保存される顔ごとにサービスによって割り当てられます。 -
イメージ ID
ImageId
、サービスによって入力イメージに割り当てられます。
すべての顔のアトリビュートをリクエストした場合(detectionAttributes
パラメータを指定すると、Amazon Rekognition は、顔のランドマーク(目と口の位置)やその他の顔の属性など、詳細な顔の属性を返します。同じイメージを指定する場合は、同じコレクションを指定し、同じ外部 ID をIndexFaces
オペレーションでは、Amazon Rekognition は重複した顔のメタデータを保存しません。
入力イメージは、base64 でエンコードされたイメージバイトとして、または Amazon S3 バケット内のイメージへの参照として渡されます。AWS CLI を使用して Amazon Rekognition オペレーションを呼び出す場合、イメージのバイトを渡すことはサポートされていません。イメージは PNG または JPEG ファイルとしてフォーマットする必要があります。
このオペレーションには rekognition:IndexFaces
アクションを実行するアクセス許可が必要です。
リクエストの構文
{
"CollectionId": "string
",
"DetectionAttributes": [ "string
" ],
"ExternalImageId": "string
",
"Image": {
"Bytes": blob
,
"S3Object": {
"Bucket": "string
",
"Name": "string
",
"Version": "string
"
}
},
"MaxFaces": number
,
"QualityFilter": "string
"
}
リクエストパラメータ
リクエストは以下の JSON 形式のデータを受け入れます。
- CollectionId
-
入力イメージで検出された顔を追加する既存のコレクションの ID。
Type: 文字列
長さの制約: 最小長は 1 です。 最大長は 255 です。
パターン:
[a-zA-Z0-9_.\-]+
必須: はい
- DetectionAttributes
-
返すフェイシャルアトリビュートの配列。これは、属性のデフォルトのリストでもすべての属性でもかまいません。に値を指定しない場合
Attributes
または、["DEFAULT"]
の場合、API は顔属性の次のサブセットを返します。BoundingBox
,Confidence
,Pose
,Quality
, およびLandmarks
。あなたが提供した場合["ALL"]
では、すべての顔のアトリビュートが返されますが、操作の完了に時間がかかります。両方を提供した場合、
["ALL", "DEFAULT"]
の場合、サービスは論理 AND 演算子を使用して、返される属性 (この場合はすべての属性) を決定します。Type: 文字列の配列
有効な値:
DEFAULT | ALL
必須: いいえ
- ExternalImageId
-
イメージで検出されたすべての顔に割り当てる ID。
Type: 文字列
長さの制約: 最小長は 1 です。 最大長は 255 です。
パターン:
[a-zA-Z0-9_.\-:]+
必須: いいえ
- Image
-
base64 でエンコードされたバイトまたは S3 オブジェクトとしての入力イメージ。AWS CLI を使用して Amazon Rekognition オペレーションを呼び出す場合、base64 でエンコードされたイメージバイトを渡すことはサポートされません。
AWS SDK を使用して Amazon Rekognition を呼び出す場合は、を使用して渡されたイメージバイトを base64 エンコードする必要がない場合があります。
Bytes
フィールド。詳細については、「イメージの仕様」を参照してください。型: Image オブジェクト
必須: はい
- MaxFaces
-
インデックスを付ける顔の最大数です。の価値
MaxFaces
は、1 以上にする必要があります。IndexFaces
より大きい値を指定した場合でも、イメージ内で検出された顔は 100 個以下で返されます。MaxFaces
。もし
IndexFaces
の値よりも多くの面を検出しますMaxFaces
では、品質が最も低いフェースが最初にフィルタアウトされます。の値よりまだ顔が多い場合MaxFaces
の場合、境界ボックスが最小であるフェースは、次の値を満たすのに必要な数までフィルタリングされます。MaxFaces
). インデックス化されていない面に関する情報は、UnindexedFaces
配列。によって返される顔
IndexFaces
は、最大のフェースバウンディングボックスのサイズで小さいサイズに降順でソートされます。MaxFaces
は、顔モデルのバージョンに関連付けられているコレクションで使用できます。Type: 整数
有効範囲: 最小値は 1 です。
必須: いいえ
- QualityFilter
-
面を識別するためのフィルタ処理量を示す品質バーを指定するフィルタ。フィルタされた顔にはインデックスが付けられません。を指定した場合
AUTO
では、Amazon Rekognition が品質バーを選択します。を指定した場合LOW
,MEDIUM
, またはHIGH
を選択すると、フィルタリングによって、選択した品質バーを満たさないすべての面が削除されます。デフォルト値はAUTO
です。品質バーは、さまざまな一般的なユースケースに基づいています。低品質の検出は、さまざまな理由で発生する可能性があります。例としては、顔と誤認される物体、ぼやけすぎた顔、または極端すぎて使用できないポーズを持つ顔などがあります。を指定した場合NONE
の場合、フィルタリングは実行されません。品質フィルタリングを使用するには、使用するコレクションがバージョン 3 以上の顔モデルに関連付けられている必要があります。
Type: 文字列
有効な値:
NONE | AUTO | LOW | MEDIUM | HIGH
必須: いいえ
レスポンスの構文
{
"FaceModelVersion": "string",
"FaceRecords": [
{
"Face": {
"BoundingBox": {
"Height": number,
"Left": number,
"Top": number,
"Width": number
},
"Confidence": number,
"ExternalImageId": "string",
"FaceId": "string",
"ImageId": "string",
"IndexFacesModelVersion": "string"
},
"FaceDetail": {
"AgeRange": {
"High": number,
"Low": number
},
"Beard": {
"Confidence": number,
"Value": boolean
},
"BoundingBox": {
"Height": number,
"Left": number,
"Top": number,
"Width": number
},
"Confidence": number,
"Emotions": [
{
"Confidence": number,
"Type": "string"
}
],
"Eyeglasses": {
"Confidence": number,
"Value": boolean
},
"EyesOpen": {
"Confidence": number,
"Value": boolean
},
"Gender": {
"Confidence": number,
"Value": "string"
},
"Landmarks": [
{
"Type": "string",
"X": number,
"Y": number
}
],
"MouthOpen": {
"Confidence": number,
"Value": boolean
},
"Mustache": {
"Confidence": number,
"Value": boolean
},
"Pose": {
"Pitch": number,
"Roll": number,
"Yaw": number
},
"Quality": {
"Brightness": number,
"Sharpness": number
},
"Smile": {
"Confidence": number,
"Value": boolean
},
"Sunglasses": {
"Confidence": number,
"Value": boolean
}
}
}
],
"OrientationCorrection": "string",
"UnindexedFaces": [
{
"FaceDetail": {
"AgeRange": {
"High": number,
"Low": number
},
"Beard": {
"Confidence": number,
"Value": boolean
},
"BoundingBox": {
"Height": number,
"Left": number,
"Top": number,
"Width": number
},
"Confidence": number,
"Emotions": [
{
"Confidence": number,
"Type": "string"
}
],
"Eyeglasses": {
"Confidence": number,
"Value": boolean
},
"EyesOpen": {
"Confidence": number,
"Value": boolean
},
"Gender": {
"Confidence": number,
"Value": "string"
},
"Landmarks": [
{
"Type": "string",
"X": number,
"Y": number
}
],
"MouthOpen": {
"Confidence": number,
"Value": boolean
},
"Mustache": {
"Confidence": number,
"Value": boolean
},
"Pose": {
"Pitch": number,
"Roll": number,
"Yaw": number
},
"Quality": {
"Brightness": number,
"Sharpness": number
},
"Smile": {
"Confidence": number,
"Value": boolean
},
"Sunglasses": {
"Confidence": number,
"Value": boolean
}
},
"Reasons": [ "string" ]
}
]
}
レスポンス要素
アクションが成功すると、サービスは HTTP 200 レスポンスを返します。
サービスから以下のデータが JSON 形式で返されます。
- FaceModelVersion
-
入力コレクションに関連付けられている顔検出モデルのバージョン番号 (
CollectionId
).Type: 文字列
- FaceRecords
-
検出され、コレクションに追加された顔の配列。詳細については、「コレクション内の顔の管理」を参照してください。
Type: の配列FaceRecordオブジェクト
- OrientationCorrection
-
コレクションがバージョン 3.0 より後の顔検出モデルに関連付けられている場合、
OrientationCorrection
は常にヌルで、方向情報は返されません。コレクションがバージョン 3.0 以前の顔検出モデルに関連付けられている場合は、以下が適用されます。
-
入力イメージが.jpeg 形式の場合、イメージの向きを含む交換可能なイメージファイル形式 (Exif) メタデータが含まれている場合があります。Amazon Rekognition は、この方向情報を使用して画像補正を実行します。Exif メタデータの方向情報を使用して画像の向きを修正した後、バウンディングボックスの座標がオブジェクトの位置を表すように変換されます。.png 形式のイメージには Exif メタデータが含まれていません。の価値
OrientationCorrection
は null です。 -
画像の Exif メタデータに方向情報が含まれていない場合、Amazon Rekognition は推定方向 (ROTATE_0、ROTATE_90、ROTATE_180、ROTATE_270) を返します。Amazon Rekognition は画像の画像補正を実行しません。バウンディングボックスの座標は変換されず、イメージが回転される前のオブジェクトの位置を表します。
バウンディングボックスの情報は、
FaceRecords
配列。を呼び出して、顔検出モデルのバージョンを入手できますDescribeCollection。Type: 文字列
有効な値:
ROTATE_0 | ROTATE_90 | ROTATE_180 | ROTATE_270
-
- UnindexedFaces
-
は、イメージ内で検出されたがインデックスが付けられていない顔の配列です。品質フィルタによって低品質であると識別されたため、インデックスが作成されませんでした。
MaxFaces
リクエストパラメータはそれらをフィルタリングしました。品質フィルタを使用するには、QualityFilter
リクエストパラメータ。Type: の配列UnindexedFaceオブジェクト
エラー
- 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
- ServiceQuotaExceededException
-
リソースのサイズが制限文字数を超えています。詳細については、「Amazon Rekognition のガイドラインとクォータ」を参照してください。
HTTP ステータスコード: 400
- ThrottlingException
-
Amazon Rekognition は一時的にリクエストを処理できませんでした。もう一度やり直してください。
HTTP ステータスコード: 500
以下の資料も参照してください。
言語固有の AWS SDK のいずれかでこの API を使用する方法の詳細については、次を参照してください: