Person Group Operations - Add Person Group Person Face

Serviço:

Azure AI Services

Versão da API:

v1.1-preview.1

Adicione um rosto a uma pessoa num Grupo de Pessoas para identificação ou verificação facial.
Para lidar com uma imagem que contém vários rostos, o rosto de entrada pode ser especificado como uma imagem com um retângulo targetFace. Devolve umFaceId persistente que representa o rosto adicionado. Nenhuma imagem será armazenada. Apenas as funcionalidades faciais extraídas serão armazenadas no servidor até que seja chamado "Eliminar Cara de Pessoa do Grupo de Pessoas", "Eliminar Pessoa do Grupo de Pessoas" ou "Eliminar Grupo de Pessoas".

Tenha em atenção que persistedFaceId é diferente do faceId gerado por "Detetar".

• • Uma maior qualidade da imagem facial significa uma melhor precisão de reconhecimento. Considere rostos de alta qualidade: frontal, claro e tamanho do rosto é 200x200 pixels (100 pixels entre os olhos) ou maior.
  • Cada entrada de pessoa pode conter até 248 rostos.
  • O formato JPEG, PNG, GIF (o primeiro fotograma) e BMP são suportados. O tamanho do ficheiro de imagem permitido é de 1KB a 6 MB.
  • O retângulo "targetFace" deve conter um rosto. Zero ou vários rostos serão considerados como um erro. Se o retângulo "targetFace" fornecido não for devolvido a partir de "Detetar", não há garantias para detetar e adicionar o rosto com êxito.
  • O tamanho do rosto detetável (36x36 - 4096x4096 pixels), uma pose de cabeça grande ou grandes oclusões causarão falhas.
  • O tamanho mínimo de rosto detetável é de 36x36 píxeis numa imagem não superior a 1920x1080 píxeis. As imagens com dimensões superiores a 1920x1080 pixels precisarão de um tamanho facial proporcionalmente maior.
  • Podem ser fornecidos diferentes valores "detectionModel". Para utilizar e comparar diferentes modelos de deteção, veja https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model

POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces

Com parâmetros opcionais:

POST {endpoint}/face/{apiVersion}/persongroups/{personGroupId}/persons/{personId}/persistedfaces?_overload=addPersonGroupPersonFace&targetFace={targetFace}&detectionModel={detectionModel}&userData={userData}

Parâmetros do URI

Name	Em	Necessário	Tipo	Description
apiVersion	path	True	string	Versão da API
endpoint	path	True	string uri	Pontos finais dos Serviços Cognitivos suportados (protocolo e nome do anfitrião, por exemplo: https://{resource-name}.cognitiveservices.azure.com).
personGroupId	path	True	string	ID do contentor. Padrão Regex: ^[a-z0-9-_]+$
personId	path	True	string uuid	ID da pessoa.
detectionModel	query		DetectionModel	O "detectionModel" associado aos faceIds detetados. Os valores "detectionModel" suportados incluem "detection_01", "detection_02" e "detection_03". O valor predefinido é "detection_01".
targetFace	query		integer[]	Um retângulo facial para especificar o rosto de destino a adicionar a uma pessoa, no formato "targetFace=left,top,width,height".
userData	query		string	Dados fornecidos pelo utilizador anexados ao rosto. O limite de tamanho é 1K.

Corpo do Pedido

Media Types: "application/octet-stream"

Name	Tipo	Description
imageContent	string	A imagem a analisar

Respostas

Name	Tipo	Description
200 OK	AddFaceResult	Uma chamada bem-sucedida devolve um novo persistedFaceId.
Other Status Codes	FaceErrorResponse	Uma resposta de erro inesperada. Cabeçalhos x-ms-error-code: string

Segurança

Ocp-Apim-Subscription-Key

A chave secreta da sua subscrição do Azure AI Face.

Tipo: apiKey
Em: header

AADToken

Fluxo OAuth2 do Azure Active Directory

Tipo: oauth2
Fluxo: accessCode
URL de Autorização: https://api.example.com/oauth2/authorize
Token URL: https://api.example.com/oauth2/token

Âmbitos

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

Exemplos

Add Face to PersonGroup Person

Pedido de amostra

HTTP

POST {endpoint}/face/v1.1-preview.1/persongroups/your_person_group_id/persons/25985303-c537-4467-b41d-bdb45cd95ca1/persistedfaces?_overload=addPersonGroupPersonFace&targetFace=10,10,100,100&detectionModel=detection_01&userData=your_user_data

"<your-image-bytes-here>"

Resposta da amostra

Código de estado:

200

{
  "persistedFaceId": "43897a75-8d6f-42cf-885e-74832febb055"
}

Definições

Name	Description
AddFaceResult	Corpo da resposta para adicionar o rosto.
DetectionModel	O "detectionModel" associado aos faceIds detetados. Os valores "detectionModel" suportados incluem "detection_01", "detection_02" e "detection_03". O valor predefinido é "detection_01".
FaceError	O objeto de erro. Para obter detalhes abrangentes sobre os códigos de erro e as mensagens devolvidas pelo Serviço Face, consulte a seguinte ligação: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Uma resposta que contém detalhes de erro.

AddFaceResult

Corpo da resposta para adicionar o rosto.

Name	Tipo	Description
persistedFaceId	string	ID do Rosto Persistente do rosto adicionado, que persiste e não expira. Diferente do faceId que é criado em "Detetar" e expira dentro de 24 horas após a chamada de deteção.

DetectionModel

O "detectionModel" associado aos faceIds detetados. Os valores "detectionModel" suportados incluem "detection_01", "detection_02" e "detection_03". O valor predefinido é "detection_01".

Name	Tipo	Description
detection_01	string	O modelo de deteção predefinido. Recomendamos a deteção de rostos quase frontal. Para cenários com rostos de ângulo excecionalmente grandes (pose de cabeça), rostos ocultos ou orientação de imagem errada, os rostos nesses casos podem não ser detetados.
detection_02	string	Modelo de deteção lançado em maio de 2019 com maior precisão, especialmente em rostos pequenos, laterais e desfocados.
detection_03	string	Modelo de deteção lançado em fevereiro de 2021 com maior precisão, especialmente em rostos pequenos.

FaceError

O objeto de erro. Para obter detalhes abrangentes sobre os códigos de erro e as mensagens devolvidas pelo Serviço Face, consulte a seguinte ligação: https://aka.ms/face-error-codes-and-messages.

Name	Tipo	Description
code	string	Um dos conjuntos de códigos de erro definidos pelo servidor.
message	string	Uma representação legível por humanos do erro.

FaceErrorResponse

Uma resposta que contém detalhes de erro.

Name	Tipo	Description
error	FaceError	O objeto de erro.