Person Directories - Find Similar Faces

Referência

Serviço:: Azure AI Services

Versão da API:: 2025-05-01-preview

Encontre rostos semelhantes.

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/faces:find?api-version=2025-05-01-preview

Parâmetros de URI

Nome	Em	Obrigatório	Tipo	Description
endpoint	path	True	string (uri)	Ponto de extremidade de serviço de Compreensão de Conteúdo.
personDirectoryId	path	True	string pattern: ^[a-zA-Z0-9._-]{1,64}$	O identificador exclusivo do diretório de pessoas.
api-version	query	True	string minLength: 1	A versão da API a ser usada para esta operação.

Cabeçalho da solicitação

Nome	Obrigatório	Tipo	Description
x-ms-client-request-id		string (uuid)	Um identificador de cadeia de caracteres opaco, globalmente exclusivo e gerado pelo cliente para a solicitação.

Corpo da solicitação

Nome	Tipo	Description
faceSource	FaceSource	Fonte do rosto.
maxSimilarFaces	integer (int32)	Número máximo de faces semelhantes a serem retornadas (até 1000).

Respostas

Nome	Tipo	Description
200 OK	FindSimilarFacesResult	A solicitação foi bem-sucedida. Cabeçalhos x-ms-client-request-id: string
Other Status Codes	Azure.Core.Foundations.ErrorResponse	Uma resposta de erro inesperada. Cabeçalhos x-ms-error-code: string

Nome

Tipo

Description

200 OK

FindSimilarFacesResult

A solicitação foi bem-sucedida.

Cabeçalhos

x-ms-client-request-id: string

Other Status Codes

Azure.Core.Foundations.ErrorResponse

Uma resposta de erro inesperada.

Cabeçalhos

x-ms-error-code: string

Segurança

Ocp-Apim-Subscription-Key

Tipo: apiKey
Em: header

OAuth2Auth

Tipo: oauth2
Flow: accessCode
URL de Autorização: https://login.microsoftonline.com/common/oauth2/authorize
URL do Token: https://login.microsoftonline.com/common/oauth2/token

Escopos

Nome	Description
https://cognitiveservices.azure.com/.default

Exemplos

Find Similar Faces

Solicitação de exemplo

HTTP

POST {endpoint}/contentunderstanding/personDirectories/myDirectory/faces:find?api-version=2025-05-01-preview

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/images/faces/face1.jpg"
  },
  "maxSimilarFaces": 10
}

Resposta de exemplo

Código de status:: 200

{
  "detectedFace": {
    "boundingBox": {
      "left": 67,
      "top": 13,
      "width": 273,
      "height": 313
    }
  },
  "similarFaces": [
    {
      "faceId": "7a87f162-8dd5-4aea-8810-373e36b96b38",
      "boundingBox": {
        "left": 33,
        "top": 73,
        "width": 262,
        "height": 324
      },
      "imageReferenceId": "face1.jpg",
      "confidence": 0.99
    },
    {
      "faceId": "f28b3cda-4005-44b6-8518-6fcddef108cb",
      "boundingBox": {
        "left": 87,
        "top": 96,
        "width": 235,
        "height": 345
      },
      "imageReferenceId": "face2.jpg",
      "confidence": 0.98
    }
  ]
}

Definições

Nome	Description
Azure.Core.Foundations.Error	O objeto de erro.
Azure.Core.Foundations.ErrorResponse	Uma resposta que contém detalhes do erro.
Azure.Core.Foundations.InnerError	Um objeto que contém informações mais específicas sobre o erro. De acordo com as diretrizes da API do Microsoft One - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.
BoundingBox	Caixa delimitadora em uma imagem.
DetectedBoundingBox	Caixa delimitadora detectada de um objeto.
FaceSource	Insira a origem da face com uma caixa delimitadora de destino opcional. Se não for especificado, a maior face será usada.
FindSimilarFacesParameters	Encontre parâmetros de faces semelhantes.
FindSimilarFacesResult	Encontre respostas de rostos semelhantes.
SimilarFace	Rosto semelhante encontrado no diretório de pessoas.

Azure.Core.Foundations.Error

Objeto

O objeto de erro.

Nome	Tipo	Description
code	string	Um de um conjunto definido pelo servidor de códigos de erro.
details	Azure.Core.Foundations.Error[]	Uma matriz de detalhes sobre erros específicos que levaram a esse erro relatado.
innererror	Azure.Core.Foundations.InnerError	Um objeto que contém informações mais específicas do que o objeto atual sobre o erro.
message	string	Uma representação do erro em formato legível por humanos.
target	string	O destino do erro.

Azure.Core.Foundations.ErrorResponse

Objeto

Uma resposta que contém detalhes do erro.

Nome	Tipo	Description
error	Azure.Core.Foundations.Error	O objeto de erro.

Azure.Core.Foundations.InnerError

Objeto

Um objeto que contém informações mais específicas sobre o erro. De acordo com as diretrizes da API do Microsoft One - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.

Nome	Tipo	Description
code	string	Um de um conjunto definido pelo servidor de códigos de erro.
innererror	Azure.Core.Foundations.InnerError	Erro interno.

BoundingBox

Objeto

Caixa delimitadora em uma imagem.

Nome	Tipo	Description
height	integer (int32)	Altura da caixa delimitadora.
left	integer (int32)	Coordenada esquerda da caixa delimitadora.
top	integer (int32)	Coordenada superior da caixa delimitadora.
width	integer (int32)	Largura da caixa delimitadora.

DetectedBoundingBox

Objeto

Caixa delimitadora detectada de um objeto.

Nome	Tipo	Description
boundingBox	BoundingBox	Caixa delimitadora da face detectada.

FaceSource

Objeto

Insira a origem da face com uma caixa delimitadora de destino opcional. Se não for especificado, a maior face será usada.

Nome	Tipo	Description
data	string (byte)	Dados de imagem codificados em Base64. Apenas um dos url ou dados deve ser especificado.
imageReferenceId	string	Identificador fornecido pelo usuário para a imagem de origem.
targetBoundingBox	BoundingBox	Caixa delimitadora que especifica a região de interesse.
url	string (uri)	URL da imagem. Apenas um dos url ou dados deve ser especificado.

FindSimilarFacesParameters

Objeto

Encontre parâmetros de faces semelhantes.

Nome	Tipo	Valor padrão	Description
faceSource	FaceSource		Fonte do rosto.
maxSimilarFaces	integer (int32)	1000	Número máximo de faces semelhantes a serem retornadas (até 1000).

FindSimilarFacesResult

Objeto

Encontre respostas de rostos semelhantes.

Nome	Tipo	Description
detectedFace	DetectedBoundingBox	Detalhes do rosto detectado.
similarFaces	SimilarFace[]	Lista de rostos semelhantes.

SimilarFace

Objeto

Rosto semelhante encontrado no diretório de pessoas.

Nome	Tipo	Description
boundingBox	BoundingBox	Caixa delimitadora da face na imagem de origem.
confidence	number (float)	Confiança de que essa face corresponde à face de entrada.
faceId	string pattern: ^[a-zA-Z0-9._-]{1,64}$	O identificador exclusivo do rosto.
imageReferenceId	string	Identificador fornecido pelo usuário para a imagem de origem.
personId	string	Pessoa associada ao rosto, se houver.

Compartilhar via

Person Directories - Find Similar Faces

Parâmetros de URI

Cabeçalho da solicitação

Corpo da solicitação

Respostas

Segurança

Ocp-Apim-Subscription-Key

OAuth2Auth

Escopos

Exemplos

Find Similar Faces

Solicitação de exemplo

Resposta de exemplo

Definições

Azure.Core.Foundations.Error

Azure.Core.Foundations.ErrorResponse

Azure.Core.Foundations.InnerError

BoundingBox

DetectedBoundingBox

FaceSource

FindSimilarFacesParameters

FindSimilarFacesResult

SimilarFace