リクエストの構文リクエストパラメータレスポンスの構文レスポンス要素エラー以下の資料も参照してください。

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リクエストパラメータ。
イメージサイズに比べて顔が小さすぎる。
顔が極端にぼやけている。
イメージが暗すぎる。
顔が極端なポーズをしている。
顔に、顔検索に適したディテールがない。

これに応えて、IndexFacesoperation は、検出されたすべての顔のメタデータの配列を返します。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 です。

パターン: [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 を使用する方法の詳細については、次を参照してください：

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

GetTextDetection

ListCollections