Person Directory Operations - Add Person Face From Url

Layanan:

Azure AI Services

Versi API:

v1.1-preview.1

Tambahkan wajah ke seseorang (lihat Direktori Orang "Create Orang") untuk identifikasi atau verifikasi wajah.
Untuk menangani gambar yang berisi beberapa wajah, wajah input dapat ditentukan sebagai gambar dengan persegi panjang targetFace. Ini mengembalikan persistedFaceId yang mewakili wajah yang ditambahkan. Tidak ada gambar yang akan disimpan. Hanya fitur wajah yang diekstrak yang akan disimpan di server hingga Direktori Orang "Hapus Wajah Orang" atau "Hapus Orang" dipanggil.

Perhatikan bahwa persistedFaceId berbeda dari faceId yang dihasilkan oleh "Detect".

• • Kualitas gambar wajah yang lebih tinggi berarti presisi pengenalan yang lebih baik. Harap pertimbangkan wajah berkualitas tinggi: ukuran depan, jernih, dan wajah adalah 200x200 piksel (100 piksel antar mata) atau lebih besar.
  • Setiap entri orang dapat menampung hingga 248 wajah.
  • Format JPEG, PNG, GIF (bingkai pertama), dan BMP didukung. Ukuran file gambar yang diizinkan adalah dari 1KB hingga 6MB.
  • Persegi panjang "targetFace" harus berisi satu wajah. Nol atau beberapa wajah akan dianggap sebagai kesalahan. Jika persegi panjang "targetFace" yang disediakan tidak dikembalikan dari "Deteksi", tidak ada jaminan untuk mendeteksi dan menambahkan wajah dengan sukses.
  • Ukuran wajah yang tidak dapat dideteksi (36x36 - 4096x4096 piksel), pose kepala besar, atau oklusi besar akan menyebabkan kegagalan.
  • Ukuran wajah minimum yang dapat dideteksi adalah 36x36 piksel dalam gambar yang tidak lebih besar dari 1920x1080 piksel. Gambar dengan dimensi yang lebih tinggi dari 1920x1080 piksel akan membutuhkan ukuran wajah minimum yang lebih besar secara proporsional.
  • Nilai 'detectionModel' yang berbeda dapat disediakan. Untuk menggunakan dan membandingkan model deteksi yang berbeda, silakan lihat https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model
• • Menambahkan/menghapus wajah ke/dari orang yang sama akan diproses secara berurutan. Menambahkan/menghapus wajah ke/dari orang yang berbeda diproses secara paralel.
  • Ini adalah operasi jangka panjang. Gunakan Header Respons "Operation-Location" untuk menentukan kapan operasi AddFace telah berhasil disebarluaskan untuk permintaan di masa mendatang ke "Identifikasi". Untuk informasi lebih lanjut tentang Operation-Locations lihat "Dapatkan Status Operasi Wajah".

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

Dengan parameter opsional:

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

Parameter URI

Nama	Dalam	Diperlukan	Jenis	Deskripsi
apiVersion	path	True	string	Versi API
endpoint	path	True	string uri	Titik akhir Cognitive Services yang didukung (protokol dan nama host, misalnya: https://{resource-name}.cognitiveservices.azure.com).
personId	path	True	string uuid	ID orang tersebut.
recognitionModel	path	True	RecognitionModel	'recognitionModel' yang terkait dengan wajah.
detectionModel	query		DetectionModel	'detectionModel' yang terkait dengan faceIds yang terdeteksi. Nilai 'detectionModel' yang didukung termasuk 'detection_01', 'detection_02' dan 'detection_03'. Nilai defaultnya adalah 'detection_01'.
targetFace	query		integer[]	Persegi panjang wajah untuk menentukan wajah target yang akan ditambahkan ke seseorang, dalam format 'targetFace=left,top,width,height'.
userData	query		string	Data yang disediakan pengguna yang dilampirkan ke wajah. Batas ukuran adalah 1K.

Isi Permintaan

Nama	Diperlukan	Jenis	Deskripsi
url	True	string	URL gambar input.

Respons

Nama	Jenis	Deskripsi
202 Accepted	AddFaceResult	Panggilan yang berhasil mengembalikan isi respons kosong. Layanan telah menerima permintaan dan akan segera mulai diproses. Klien dapat mengkueri status operasi dan hasil menggunakan URL yang ditentukan di header respons 'Lokasi Operasi'. URL kedaluwarsa dalam 48 jam. Header Location: string operation-Location: string
Other Status Codes	FaceErrorResponse	Respons kesalahan yang tidak terduga. Header x-ms-error-code: string

Keamanan

Ocp-Apim-Subscription-Key

Kunci rahasia untuk langganan Azure AI Face Anda.

Jenis: apiKey
Dalam: header

AADToken

Alur OAuth2 Azure Active Directory

Jenis: oauth2
Alur: accessCode
URL Otorisasi: https://api.example.com/oauth2/authorize
URL token: https://api.example.com/oauth2/token

Cakupan

Nama	Deskripsi
https://cognitiveservices.azure.com/.default

Contoh

Add Face to PersonDirectory Person from Url

Permintaan sampel

HTTP

POST {endpoint}/face/v1.1-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"
}

Respon sampel

Kode status:

202

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

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

Definisi

Nama	Deskripsi
AddFaceResult	Isi respons untuk menambahkan wajah.
DetectionModel	'detectionModel' yang terkait dengan faceIds yang terdeteksi. Nilai 'detectionModel' yang didukung termasuk 'detection_01', 'detection_02' dan 'detection_03'. Nilai defaultnya adalah 'detection_01'.
FaceError	Objek kesalahan. Untuk detail komprehensif tentang kode kesalahan dan pesan yang dikembalikan oleh Face Service, silakan lihat tautan berikut: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Respons yang berisi detail kesalahan.
RecognitionModel	Model pengenalan untuk wajah.

AddFaceResult

Isi respons untuk menambahkan wajah.

Nama	Jenis	Deskripsi
persistedFaceId	string	FACE ID persisten dari wajah yang ditambahkan, yang bertahan dan tidak akan kedaluwarsa. Berbeda dari faceId yang dibuat di "Deteksi" dan akan kedaluwarsa dalam 24 jam setelah panggilan deteksi.

DetectionModel

'detectionModel' yang terkait dengan faceIds yang terdeteksi. Nilai 'detectionModel' yang didukung termasuk 'detection_01', 'detection_02' dan 'detection_03'. Nilai defaultnya adalah 'detection_01'.

Nama	Jenis	Deskripsi
detection_01	string	Model deteksi default. Rekomendasi untuk deteksi wajah frontal dekat. Untuk skenario dengan wajah sudut (pose kepala) yang sangat besar, wajah oklud atau orientasi gambar yang salah, wajah dalam kasus seperti itu mungkin tidak terdeteksi.
detection_02	string	Model deteksi dirilis pada tahun 2019 Mei dengan akurasi yang ditingkatkan terutama pada wajah kecil, samping dan buram.
detection_03	string	Model deteksi dirilis pada februari 2021 dengan akurasi yang ditingkatkan terutama pada wajah kecil.

FaceError

Objek kesalahan. Untuk detail komprehensif tentang kode kesalahan dan pesan yang dikembalikan oleh Face Service, silakan lihat tautan berikut: https://aka.ms/face-error-codes-and-messages.

Nama	Jenis	Deskripsi
code	string	Salah satu set kode kesalahan yang ditentukan server.
message	string	Representasi kesalahan yang dapat dibaca manusia.

FaceErrorResponse

Respons yang berisi detail kesalahan.

Nama	Jenis	Deskripsi
error	FaceError	Objek kesalahan.

RecognitionModel

Model pengenalan untuk wajah.

Nama	Jenis	Deskripsi
recognition_01	string	Model pengenalan default untuk "Deteksi". Semua faceId yang dibuat sebelum 2019 Maret diikat dengan model pengenalan ini.
recognition_02	string	Model pengenalan dirilis pada bulan Maret 2019.
recognition_03	string	Model pengenalan dirilis pada bulan Mei 2020.
recognition_04	string	Model pengenalan dirilis pada februari 2021. Disarankan untuk menggunakan model pengenalan ini untuk akurasi pengenalan yang lebih baik.