SearchFacesByImage

Para uma determinada imagem de entrada, primeiro detecta a maior face na imagem e, em seguida, pesquisa faces correspondentes na coleção especificada. A operação compara os recursos da face de entrada com faces na coleção especificada.

nota

Para procurar todas as faces em uma imagem de entrada, você pode primeiro chamar oIndexFacese, em seguida, use os IDs de face retornados em chamadas subsequentes para oSearchFacesoperação.

Você também pode chamar aDetectFacesoperação e use as caixas delimitadoras na resposta para fazer culturas faciais, que então você pode passar para oSearchFacesByImageoperação.

Você passa a imagem de entrada como bytes de imagem codificados em base64 ou como referência a uma imagem em um bucket do Amazon S3. Se você usar a AWS CLI para chamar operações do Amazon Rekognition, não será oferecido o suporte à passagem de bytes da imagem. A imagem deve ser um arquivo PNG ou JPEG formatado.

A resposta retorna uma matriz de faces que correspondem, ordenadas pela pontuação de similaridade com a maior semelhança primeiro. Mais especificamente, é uma matriz de metadados para cada correspondência facial encontrada. Junto com os metadados, a resposta também inclui umsimilarityindicando como o rosto é semelhante à face de entrada. Na resposta, a operação também retorna a caixa delimitadora (e um nível de confiança que a caixa delimitadora contém uma face) da face que o Amazon Rekognition usou para a imagem de entrada.

Se nenhuma face for detectada na imagem de entrada,SearchFacesByImageretorna umInvalidParameterException(Nenhum console do Windows encontrado. Você está executando o cmd.exe?”.

Para ver um exemplo, consulte Procurando por um rosto usando uma imagem.

OQualityFilterparâmetro de entrada permite filtrar faces detectadas que não atendem a uma barra de qualidade necessária. A barra de qualidade é baseada em uma variedade de casos de uso comuns. Usar oQualityFilterpara definir a barra de qualidade para filtragem especificandoLOW,MEDIUM, ouHIGH. Se você não quiser filtrar faces detectadas, especifiqueNONE. O valor padrão é NONE.

nota

Para usar a filtragem de qualidade, você precisa de uma coleção associada à versão 3 do modelo de faces ou posterior. Para obter a versão do modelo de face associado a uma coleção, chame DescribeCollection.

Essa operação exige permissões para executar a ação rekognition:SearchFacesByImage.

Sintaxe da solicitação

{
   "CollectionId": "string",
   "FaceMatchThreshold": number,
   "Image": { 
      "Bytes": blob,
      "S3Object": { 
         "Bucket": "string",
         "Name": "string",
         "Version": "string"
      }
   },
   "MaxFaces": number,
   "QualityFilter": "string"
}

Parâmetros de solicitação

A solicitação aceita os dados a seguir no formato JSON.

CollectionId

ID da coleção a ser pesquisada.

Type: String

Restrições de comprimento: Tamanho mínimo de 1. Tamanho máximo de 255.

Padrão: [a-zA-Z0-9_.\-]+

Obrigatório: Sim

FaceMatchThreshold

(Opcional) Especifica a confiança mínima na correspondência facial para retornar. Por exemplo, não retorne nenhuma correspondência em que a confiança nas partidas seja inferior a 70%. O valor padrão é 80%.

Type: Float

Intervalo válido: Valor mínimo de 0. Valor máximo de 100.

Obrigatório: Não

Image

A imagem de entrada como bytes codificados em base64 ou um objeto S3. Se você usar a AWS CLI para chamar operações do Amazon Rekognition, não será oferecido o suporte à passagem de bytes da imagem codificados em base64.

Se você estiver usando um AWS SDK para chamar o Amazon Rekognition, talvez não seja necessário codificar bytes de imagem com base 64 passados usando oBytescampo. Para obter mais informações, consulte Especificações da imagem.

Tipo: objeto Image

Obrigatório: Sim

MaxFaces

O número máximo de faces a serem retornadas. A operação retorna o número máximo de faces com a maior confiança na partida.

Type: Inteiro

Intervalo válido: Valor mínimo de 1. Valor máximo de 4.096.

Obrigatório: Não

QualityFilter

Um filtro que especifica uma barra de qualidade para quanta filtragem é feita para identificar rostos. Rostos filtrados não são pesquisados na coleção. Se você especificarAUTO, o Amazon Rekognition escolhe a barra de qualidade. Se você especificarLOW,MEDIUM, ouHIGH, a filtragem remove todas as faces que não atendem à barra de qualidade escolhida. A barra de qualidade é baseada em uma variedade de casos de uso comuns. Detecções de baixa qualidade podem ocorrer por vários motivos. Alguns exemplos são um objeto identificado erroneamente como um rosto, um rosto muito embaçado ou um rosto com uma pose muito extrema para usar. Se você especificarNONE, nenhuma filtragem é executada. O valor padrão é NONE.

Para usar a filtragem de qualidade, a coleção que você está usando deve estar associada à versão 3 do modelo de faces ou posterior.

Type: String

Valores válidos: NONE | AUTO | LOW | MEDIUM | HIGH

Obrigatório: Não

Sintaxe da resposta

{
   "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
}

Elementos de resposta

Se a ação for bem-sucedida, o serviço reenviará uma resposta HTTP 200.

Os seguintes dados são retornados no formato JSON pelo serviço.

FaceMatches

Uma matriz de faces que correspondem à face de entrada, juntamente com a confiança na partida.

Type: Matriz deFaceMatchobjetos

FaceModelVersion

Número de versão do modelo de detecção de faces associado à coleção de entrada (CollectionId).

Type: String

SearchedFaceBoundingBox

A caixa delimitadora ao redor da face na imagem de entrada que o Amazon Rekognition usou para a pesquisa.

Tipo: objeto BoundingBox

SearchedFaceConfidence

O nível de confiança dosearchedFaceBoundingBox, contém um rosto.

Type: Float

Intervalo válido: Valor mínimo de 0. Valor máximo de 100.

Erros

AccessDeniedException

Você não está autorizado a executar a ação.

Código de status HTTP: 400

ImageTooLargeException

O tamanho da imagem de entrada excede o limite permitido. Se você estiver ligandoDetectProtectiveEquipment, o tamanho da imagem ou a resolução excede o limite permitido. Para obter mais informações, consulte Diretrizes e cotas no Amazon Rekognition.

Código de status HTTP: 400

InternalServerError

O Amazon Rekognition teve um problema de serviço. Tente fazer a chamada novamente.

Código de status HTTP: 500

InvalidImageFormatException

O formato da imagem fornecida não é compatível.

Código de status HTTP: 400

InvalidParameterException

Um parâmetro de entrada violou uma restrição. Valide seu parâmetro antes de chamar a operação da API novamente.

Código de status HTTP: 400

InvalidS3ObjectException

O Amazon Rekognition não pode acessar o objeto do S3 especificado na solicitação.

Código de status HTTP: 400

ProvisionedThroughputExceededException

O número de solicitações excedeu o limite da taxa de transferência. Se precisar aumentar esse limite, entre em contato com o Amazon Rekognition.

Código de status HTTP: 400

ResourceNotFoundException

O recurso especificado na solicitação não pode ser encontrado.

Código de status HTTP: 400

ThrottlingException

O Amazon Rekognition está temporariamente indisponível para processar a solicitação. Tente fazer a chamada novamente.

Código de status HTTP: 500

Consulte também

Para obter mais informações sobre como usar essa API em um dos AWS SDKs específicos de linguagem, consulte o seguinte:

• AWS Command Line Interface

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go

• AWSSDK for Java V2

• AWS SDK for JavaScript

• AWS SDK para PHP V3

• AWS SDK para Python

• AWS SDK for Ruby V3