共用方式為


Face List - Add Face From Stream

將臉部新增至指定的臉部清單,最多 1,000 張臉部。
若要處理影像包含多個臉部,輸入臉部可以指定為具有 targetFace 矩形的影像。 它會傳回代表新增臉部的persistedFaceId。 不會儲存任何影像。 只有擷取的臉部功能會儲存在伺服器上,直到 呼叫FaceList - Delete 臉部FaceList - Delete 為止。
注意 persistedFaceId 與 Face - Detect 所產生的 faceId 不同。

  • 較高的臉部影像品質表示更好的偵測和辨識精確度。 請考慮高品質的臉部:正面、清楚和臉部大小為 200x200 像素, (100 像素在眼睛之間) 或更大。
  • 支援 JPEG、PNG、GIF (第一個畫面格) 和 BMP 格式。 允許的映像檔大小從 1KB 到 6MB。
  • “targetFace” 矩形應該包含一個臉部。 零或多個臉部會被視為錯誤。 如果提供的 「targetFace」 矩形未從 臉部 - 偵測傳回,則不保證可以偵測並成功新增臉部。
  • 無法偵測到的臉部大小 (36x36 - 4096x4096 像素) 、大型頭部姿勢或大型遮蔽會導致失敗。
  • 將臉部新增/刪除至相同臉部清單或從相同臉部清單進行循序處理,且從不同的臉部清單平行處理。
  • 影像中可偵測的最小臉部大小為 36x36 像素,不超過 1920x1080 圖元。 維度高於 1920x1080 像素的影像需要比例較大的最小臉部大小。
  • 您可以提供不同的 'detectionModel' 值。 若要使用和比較不同的偵測模型,請參閱 如何指定偵測模型
POST {Endpoint}/face/v1.0/facelists/{faceListId}/persistedfaces
POST {Endpoint}/face/v1.0/facelists/{faceListId}/persistedfaces?overload=stream&userData={userData}&targetFace={targetFace}&detectionModel={detectionModel}

URI 參數

名稱 位於 必要 類型 Description
Endpoint
path True

string

支援的認知服務端點 (通訊協定和主機名,例如: https://westus.api.cognitive.microsoft.com) 。

faceListId
path True

string

參考特定臉部清單的標識碼。

Regex 模式: ^[a-z0-9-_]+$

detectionModel
query

DetectionModel

偵測模型的名稱。 偵測模型可用來偵測提交影像中的臉部。 執行臉部時,可以提供偵測模型名稱 - 偵測或 (大型) FaceList - 新增臉部或 (大型) PersonGroup - 新增臉部。 默認值為 『detection_01』,如果需要另一個模型,請明確指定它。

targetFace
query

integer[]

臉部矩形,指定要以 「targetFace=left,top,width,height」 格式新增至人員的目標臉部。 例如“targetFace=10,10,100,100”。 如果影像中有多個臉部,則需要 targetFace 來指定要新增的臉部。 沒有 targetFace 表示整個影像中只偵測到一個臉部。

userData
query

string

任何用途之臉部的使用者指定數據。 最大長度為 1KB。

要求標頭

Media Types: "application/octet-stream"

名稱 必要 類型 Description
Ocp-Apim-Subscription-Key True

string

要求本文

Media Types: "application/octet-stream"

名稱 類型 Description
Image

object

影像數據流。

回應

名稱 類型 Description
200 OK

PersistedFace

成功的呼叫會傳回新的persistedFaceId。

Other Status Codes

APIError

錯誤回應。

安全性

Ocp-Apim-Subscription-Key

類型: apiKey
位於: header

範例

Add face to face list from stream example

範例要求

POST {Endpoint}/face/v1.0/facelists/sample_face_list/persistedfaces?overload=stream&userData={Customized user data}&targetFace=10,10,100,100&detectionModel=detection_01


"{Image stream in base 64 encoded format}"

範例回覆

{
  "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA"
}

定義

名稱 Description
APIError

API 傳回的錯誤資訊

DetectionModel

偵測模型的名稱。 偵測模型可用來偵測提交影像中的臉部。 執行臉部時,可以提供偵測模型名稱 - 偵測或 (大型) FaceList - 新增臉部或 (大型) PersonGroup - 新增臉部。 默認值為 『detection_01』,如果需要另一個模型,請明確指定它。

Error

錯誤本文。

PersistedFace

PersonFace 物件。

APIError

API 傳回的錯誤資訊

名稱 類型 Description
error

Error

錯誤本文。

DetectionModel

偵測模型的名稱。 偵測模型可用來偵測提交影像中的臉部。 執行臉部時,可以提供偵測模型名稱 - 偵測或 (大型) FaceList - 新增臉部或 (大型) PersonGroup - 新增臉部。 默認值為 『detection_01』,如果需要另一個模型,請明確指定它。

名稱 類型 Description
detection_01

string

detection_02

string

detection_03

string

Error

錯誤本文。

名稱 類型 Description
code

string

message

string

PersistedFace

PersonFace 物件。

名稱 類型 Description
persistedFaceId

string

已保存且不會過期的目標臉部persistedFaceId。 不同於 Face - Detect 所建立的 faceId,且會在偵測呼叫之後由 faceIdTimeToLive 指定的時間到期。

userData

string

使用者提供的數據會附加至臉部。 大小限製為 1KB。