As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
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.
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 umaInvalidParameterExceptionERROR.
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.
Para usar a filtragem de qualidade, é necessário ter uma coleção associada com a 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 o
Bytescampo. Para obter mais informações, consulte Especificações de 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 4096.
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ê especificar
AUTO, 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 uma série de razões. 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 com a versão 3 do modelo de faces ou posterior.
Type: String
Valores válidos:
NONE | AUTO | LOW | MEDIUM | HIGHObrigató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
-
Modelo de rosto mais recente sendo usado com a coleção. Para obter mais informações, consulteVersionamento de modelo.
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 do
searchedFaceBoundingBox, contém um rosto.Type: Float
Intervalo válido: Valor mínimo de 0. Valor máximo de 100.
Errors
- 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
-
O 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:
