Person Directory Operations - Add Person Face From Url

Servizio:

Azure AI Services

Versione API:

v1.2-preview.1

Aggiungere un viso a una persona (vedere Person Directory "Create Person") per l'identificazione o la verifica del viso.
Per gestire un'immagine contenente più visi, è possibile specificare il viso di input come immagine con un rettangolo targetFace. Restituisce un elemento persistedFaceId che rappresenta il viso aggiunto. Nessuna immagine verrà archiviata. Solo le caratteristiche del viso estratte verranno archiviate nel server finché non viene chiamata la directory delle persone "Elimina viso persona" o "Elimina persona".

Si noti che persistedFaceId è diverso da faceId generato da "Detect".

• • Maggiore qualità dell'immagine del viso significa una migliore precisione di riconoscimento. Si prega di considerare i visi di alta qualità: le dimensioni frontali, chiare e del viso sono di 200x200 pixel (100 pixel tra gli occhi) o più grandi.
  • Ogni voce può contenere fino a 248 visi.
  • Sono supportati JPEG, PNG, GIF (il primo fotogramma) e il formato BMP. Le dimensioni consentite del file di immagine sono da 1 KB a 6 MB.
  • Il rettangolo "targetFace" deve contenere un viso. Zero o più visi verranno considerati come un errore. Se il rettangolo "targetFace" specificato non viene restituito da "Detect", non esiste alcuna garanzia per rilevare e aggiungere correttamente il viso.
  • Le dimensioni del viso non rilevabili (36x36 - 4096x4096 pixel), la posizione della testa grande o le occlusioni di grandi dimensioni causeranno errori.
  • La dimensione minima del viso rilevabile è di 36x36 pixel in un'immagine non superiore a 1920x1080 pixel. Le immagini con dimensioni superiori a 1920x1080 pixel avranno bisogno di una dimensione minima minima proporzionale.
  • È possibile specificare valori diversi di 'detectionModel'. Per usare e confrontare modelli di rilevamento diversi, vedere https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model
• • L'aggiunta/eliminazione di visi da e verso una stessa persona verrà elaborata in sequenza. L'aggiunta/eliminazione di visi da/verso persone diverse viene elaborata in parallelo.
  • Si tratta di un'operazione a esecuzione prolungata. Usare l'intestazione di risposta "Operation-Location" per determinare quando l'operazione AddFace è stata propagata correttamente per le future richieste a "Identify". Per altre informazioni su Operation-Locations vedere "Get Face Operation Status".

POST {endpoint}/face/{apiVersion}/persons/{personId}/recognitionModels/{recognitionModel}/persistedfaces

Con parametri facoltativi:

POST {endpoint}/face/{apiVersion}/persons/{personId}/recognitionModels/{recognitionModel}/persistedfaces?_overload=addPersonFaceFromUrl&targetFace={targetFace}&detectionModel={detectionModel}&userData={userData}

Parametri dell'URI

Nome	In	Necessario	Tipo	Descrizione
apiVersion	path	True	string	Versione API
endpoint	path	True	string uri	Endpoint di Servizi cognitivi supportati (protocollo e nome host, ad esempio: https://{nome-risorsa}.cognitiveservices.azure.com).
personId	path	True	string uuid	ID persona della persona.
recognitionModel	path	True	RecognitionModel	'recognitionModel' associato ai visi.
detectionModel	query		DetectionModel	'detectionModel' associato ai faceId rilevati. I valori 'detectionModel' supportati includono 'detection_01', 'detection_02' e 'detection_03'. Il valore predefinito è 'detection_01'.
targetFace	query		integer[]	Rettangolo del viso per specificare il viso di destinazione da aggiungere a una persona, nel formato 'targetFace=left,top,width,height'.
userData	query		string	Dati forniti dall'utente collegati al viso. Il limite di dimensioni è 1K.

Corpo della richiesta

Nome	Necessario	Tipo	Descrizione
url	True	string	URL dell'immagine di input.

Risposte

Nome	Tipo	Descrizione
202 Accepted	AddFaceResult	Una chiamata con esito positivo restituisce un corpo di risposta vuoto. Il servizio ha accettato la richiesta e inizierà presto l'elaborazione. Il client può eseguire una query sullo stato dell'operazione e ottenere il risultato usando l'URL specificato nell'intestazione della risposta 'Operation-Location'. L'URL scade entro 48 ore. Intestazioni Location: string operation-Location: string
Other Status Codes	FaceErrorResponse	Risposta di errore imprevista. Intestazioni x-ms-error-code: string

Sicurezza

Ocp-Apim-Subscription-Key

Chiave privata per la sottoscrizione di Viso di Intelligenza artificiale di Azure.

Tipo: apiKey
In: header

AADToken

Flusso OAuth2 di Azure Active Directory

Tipo: oauth2
Flow: accessCode
URL di autorizzazione: https://api.example.com/oauth2/authorize
URL token: https://api.example.com/oauth2/token

Ambiti

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

Esempio

Add Face to PersonDirectory Person from Url

Esempio di richiesta

HTTP

POST {endpoint}/face/v1.2-preview.1/persons/85c0c630-c9c9-40f8-8a4e-f9ae4f926ea5/recognitionModels/recognition_01/persistedfaces?_overload=addPersonFaceFromUrl&targetFace=10,10,100,100&detectionModel=detection_01&userData=your_user_data

{
  "url": "https://microsoft.com/example.jpg"
}

Risposta di esempio

Codice di stato:

202

location: https://contoso.com/operationstatus
operation-Location: https://contoso.com/operationstatus

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

Definizioni

Nome	Descrizione
AddFaceResult	Corpo della risposta per l'aggiunta del viso.
DetectionModel	'detectionModel' associato ai faceId rilevati. I valori 'detectionModel' supportati includono 'detection_01', 'detection_02' e 'detection_03'. Il valore predefinito è 'detection_01'.
FaceError	Oggetto error. Per informazioni dettagliate sui codici di errore e i messaggi restituiti dal servizio Viso, vedere il collegamento seguente: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Risposta contenente i dettagli dell'errore.
RecognitionModel	Modello di riconoscimento per il viso.

AddFaceResult

Corpo della risposta per l'aggiunta del viso.

Nome	Tipo	Descrizione
persistedFaceId	string	L'ID viso persistente del viso aggiunto, che viene salvato in modo permanente e non scadrà. Diverso da faceId creato in "Rileva" e scadrà in 24 ore dopo la chiamata di rilevamento.

DetectionModel

'detectionModel' associato ai faceId rilevati. I valori 'detectionModel' supportati includono 'detection_01', 'detection_02' e 'detection_03'. Il valore predefinito è 'detection_01'.

Nome	Tipo	Descrizione
detection_01	string	Modello di rilevamento predefinito. Consigliato per il rilevamento dei visi quasi frontali. Per scenari con visi ad angolo estremamente grande (posizione della testa), volti occlusi o orientamento errato dell'immagine, i visi in tali casi potrebbero non essere rilevati.
detection_02	string	Modello di rilevamento rilasciato nel 2019 maggio con una maggiore precisione soprattutto sui visi piccoli, laterali e sfocati.
detection_03	string	Modello di rilevamento rilasciato nel 2021 febbraio con una maggiore accuratezza soprattutto sui visi piccoli.

FaceError

Oggetto error. Per informazioni dettagliate sui codici di errore e i messaggi restituiti dal servizio Viso, vedere il collegamento seguente: https://aka.ms/face-error-codes-and-messages.

Nome	Tipo	Descrizione
code	string	Uno di un set definito dal server di codici di errore.
message	string	Rappresentazione leggibile dell'errore.

FaceErrorResponse

Risposta contenente i dettagli dell'errore.

Nome	Tipo	Descrizione
error	FaceError	Oggetto error.

RecognitionModel

Modello di riconoscimento per il viso.

Nome	Tipo	Descrizione
recognition_01	string	Modello di riconoscimento predefinito per "Detect". Tutti i faceId creati prima del 2019 marzo sono associati a questo modello di riconoscimento.
recognition_02	string	Modello di riconoscimento rilasciato nel marzo 2019.
recognition_03	string	Modello di riconoscimento rilasciato nel maggio 2020.
recognition_04	string	Modello di riconoscimento rilasciato nel 2021 febbraio. È consigliabile usare questo modello di riconoscimento per migliorare l'accuratezza del riconoscimento.