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操作は、検出されたすべての面のメタデータの配列を返します。FaceRecords。ここでは次の点について説明します。

• 境界ボックスであるBoundingBox、検出された顔の。

• 信頼値、Confidenceは、境界ボックス内に顔が含まれている信頼度を示します。

• フェイス ID、FaceIdは、検出されて保存された顔ごとにサービスによって割り当てられます。

• イメージ IDImageIdで、入力イメージのサービスによって割り当てられます。

すべての顔の属性を要求した場合 (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 です。

Pattern: [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 です。

Pattern: [a-zA-Z0-9_.\-:]+

必須: いいえ

Image

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

AWS SDK を使用して Amazon Rekognition を呼び出す場合は、Bytesフィールド。詳細については、「イメージの仕様」を参照してください。

タイプ: Image オブジェクト

必須: はい

MaxFaces

インデックス化する顔の最大数。valueMaxFacesは、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"
         },
         "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 objects

OrientationCorrection

コレクションがバージョン 3.0 より後の顔検出モデルに関連付けられている場合、OrientationCorrectionは常にnullであり、方向情報は返されません。

コレクションがバージョン 3.0 以前の顔検出モデルに関連付けられている場合、次のことが適用されます。

• 入力イメージが .jpeg 形式の場合、イメージの方向を含む交換可能なイメージファイル形式 (Exif) メタデータが含まれる場合があります。Amazon Rekognition はこの方向情報を使用して画像補正を実行します。Exif メタデータの方向情報を使用して画像の向きを修正した後、バウンディングボックスの座標がオブジェクトの位置を表すように変換されます。.png 形式のイメージには Exif メタデータが含まれていません。valueOrientationCorrectionは 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 objects

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

ServiceQuotaExceededException

リソースサイズが制限文字数を超えています。詳細については、「Amazon Rekognition のガイドラインとクォータ」を参照してください。

HTTP ステータスコード: 400

ThrottlingException

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

HTTP ステータスコード: 500

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

言語固有のAWSSDK については、以下を参照してください。

• AWS コマンドラインインターフェイス

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go

• AWS SDK for Java V2

• AWS SDK for JavaScript

• AWS SDK for PHP V3

• AWS SDK for Python

• AWS SDK for Ruby V3