Partilhar via


Person Group Operations - Add Person Group Person Face

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
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

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

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