使用 Azure AI Video Indexer API 來遮蔽臉部

發行項
07/26/2024

重要

由於已淘汰 Azure 媒體服務，移轉 Azure 影片索引器內容的期限已過。如需詳細資訊，請參閱淘汰指南。

您可以使用 Azure AI Video Indexer 來偵測及識別影片中的臉部。您可以使用 API 來修改您的影片以模糊 (遮蔽) 特定個人的臉部。

若要手動遮蔽包含多個臉部的幾分鐘影片，可能要花上數小時的時間，但透過 Video Indexer API 中的預設設定，則只需要幾個簡單的步驟就能完成臉部遮蔽程序。

本文說明如何使用 API 來遮蔽臉部。 Video Indexer API 包含臉部遮蔽預設選項，可在雲端中提供可調整的臉部偵測和遮蔽 (模糊) 功能。本文會詳細示範使用 API 遮蔽臉部的每個步驟。

下列影片示範如何使用 Azure AI Video Indexer API 來遮蔽影片。

合規性、隱私權和安全性

事先提醒，在使用 Video Indexer 取得分析和深入解析時，您必須遵守所有適用的法律。

臉部辨識服務存取受到資格和使用準則限制，以支援 Microsoft 負責任的 AI 原則。臉部辨識服務僅供由 Microsoft 管理的客戶和合作夥伴使用。請使用臉部辨識受理表單以申請存取。如需詳細資訊，請參閱臉部的有限存取權頁面。

臉部遮蔽術語和階層

Video Indexer 中的臉部遮蔽功能，依賴於我們在影片標準和進階分析預設中提供的現有 Video Indexer 臉部偵測結果輸出。

若要遮蔽影片，您必須先將影片上傳至 Video Indexer，並使用 [標準] 或 [進階] 影片預設值來完成分析。您可以使用 Azure AI 影片索引器網站或 API 來執行此動作。接著，您可以使用 videoId 值以透過臉部遮蔽 API 參考此影片。我們會建立新的影片，並將已標示的臉部進行遮蔽。影片分析和臉部遮蔽是個別計費的作業。如需詳細資訊，請參閱我們的價格頁面。

模糊的類型

您可以在臉部遮蔽中選擇不同類型的模糊。若要選取類型，請在要求本文中使用 blurringKind 參數的名稱或代表編號：

blurringKind 編號	blurringKind 名稱	範例
0	MediumBlur
1	HighBlur
2	LowBlur
3	BoundingBox
4	黑色

您可以在要求本文中使用 blurringKind 參數來指定模糊的類型。

以下是範例：

{
    "faces": {
        "blurringKind": "HighBlur"
    }
}

或者，使用上表所述模糊類型的代表編號：

{
    "faces": {
        "blurringKind": 1
    }
}

篩選

您可以套用篩選來設定要模糊的臉部識別碼。您可在 JSON 檔案主體的逗號分隔陣列中指定臉部識別碼。使用 scope 參數將這些臉部排除或包含在遮蔽範圍內。藉由指定識別碼，您可以編輯所有臉部但「排除」所選識別碼，或是「只需」遮蔽所選識別碼。請參閱下一節中的範例。

排除範圍

在下列範例中，若要遮蔽臉部識別碼 1001 和 1016 以外的所有臉部，請使用 Exclude 範圍：

{
    "faces": {
        "blurringKind": "HighBlur",
        "filter": {
            "ids": [1001, 1016],
            "scope": "Exclude"
        }
    }
}

包含範圍

在下列範例中，若只需遮蔽臉部識別碼 1001 和 1016，請使用 Include 範圍：

{
    "faces": {
        "blurringKind": "HighBlur",
        "filter": {
            "ids": [1001, 1016],
            "scope": "Include"
        }
    }
}

遮蔽所有臉部

若要遮蔽所有臉部，請移除範圍篩選：

{
    "faces": {
        "blurringKind": "HighBlur",
    }
}

若要擷取臉部識別碼，您可以移至已編製索引的影片，並擷取成品檔案。成品包含 faces.json 檔案和縮圖 .zip 檔案，當中會包含影片裡偵測到的所有臉部。您可以比對臉部與識別碼，並決定要遮蔽的臉部識別碼。

建立遮蔽作業

若要建立遮蔽作業，您可以叫用下列 API 呼叫：

POST https://api.videoindexer.ai/{location}/Accounts/{accountId}/Videos/{videoId}/redact[?name][&priority][&privacy][&externalId][&streamingPreset][&callbackUrl][&accessToken]

下列為必要值：

名稱	數值	Description
`Accountid`	`{accountId}`	Video Indexer 帳戶的識別碼。
`Location`	`{location}`	Video Indexer 帳戶所在的 Azure 區域。例如 westus。
`AccessToken`	`{token}`	權杖，具有透過 Azure Resource Manager REST API 產生的「帳戶參與者」權限。
`Videoid`	`{videoId}`	待遮蔽來源影片的影片識別碼。您可以使用清單影片 API 來擷取影片識別碼。
`Name`	`{name}`	遮蔽後的新影片名稱。

以下是要求的範例：

https://api.videoindexer.ai/westeurope/Accounts/{id}/Videos/{id}/redact?priority=Low&name=testredaction&privacy=Private&streamingPreset=Default

您可以將權杖指定為索引鍵實值型別 bearertoken:{token} 的授權標頭，或使用 ?token={token} 以查詢參數形式提供。

您也需要新增 JSON 格式的要求本文，包含要套用的遮蔽作業選項。以下是範例：

{
    "faces": {
        "blurringKind": "HighBlur"
    }
}

要求成功時，您會收到回應 HTTP 202 ACCEPTED。

監試工作狀態

在作業建立要求的回應中，您會收到具有作業 URL 的 HTTP 標頭 Location。您可以使用相同的權杖向此 URL 提出 GET 要求，以查看遮蔽作業的狀態。

範例 URL 如下：

https://api.videoindexer.ai/westeurope/Accounts/<id>/Jobs/<id>

以下是範例回應：

{
    "creationTime": "2023-05-11T11:22:57.6114155Z",
    "lastUpdateTime": "2023-05-11T11:23:01.7993563Z",
    "progress": 20,
    "jobType": "Redaction",
    "state": "Processing"
}

如果您在完成遮蔽作業時呼叫相同的 URL，請在 Location 標頭中取得已遮蔽影片的儲存體共用存取簽章 (SAS) URL。例如：

https://api.videoindexer.ai/westeurope/Accounts/<id>/Videos/<id>/SourceFile/DownloadUrl

此 URL 會重新導向至儲存在 Azure 儲存體帳戶中的 .mp4 檔案。

常見問題集

問題	回答
我可以在一項作業中同時上傳影片並遮蔽嗎？	否。您必須先使用 Video Indexer API 上傳和分析影片。接著，在遮蔽作業中參考已編製索引的影片。
我可以使用 Azure AI Video Indexer 網站來遮蔽影片嗎？	否。目前只能使用 API 來建立遮蔽作業。
我可以使用 Video Indexer 網站播放已遮蔽的影片嗎？	是。 Video Indexer 網站上會顯示已遮蔽的影片，如同其他已編製索引的影片一樣，但不包含任何深入解析。
如何刪除已遮蔽的影片？	您可以使用刪除影片 API，並提供已遮蔽影片的 `Videoid` 值。
使用臉部遮蔽需要通過臉部識別管制嗎？	除非您代表美國的警察部門，否則不需要。即使您受到管制，我們仍會繼續提供臉部偵測功能。如果您受到管制，則我們不會提供臉部識別功能。不過，您可以僅使用臉部偵測來遮蔽影片中的所有臉部。
臉部遮蔽是否會覆寫我的原始影片？	否。臉部遮蔽作業會建立新的影片輸出檔案。
並未正確遮蔽所有臉部。我能做什麼?	遮蔽依賴於分析管線的初始臉部偵測和追蹤輸出。雖然我們通常都能偵測到所有臉部，但在某些情況下會無法偵測到臉部。臉部角度、臉部出現的幀數、來源影片的畫質等因素都會影響臉部遮蔽的品質。如需詳細資訊，請參閱臉部深入解析。
我可以遮蔽臉部以外的物件嗎？	否。目前我們只提供臉部遮蔽。如果您需要遮蔽其他物件，您可以在 Azure User Voice 頻道中向我們提供產品的意見反應。
已遮蔽影片的下載 SAS URL 有效期限為何？	若要在 SAS URL 過期之後下載已遮蔽的影片，您必須呼叫初始作業狀態 URL。建議將這些 `Jobstatus` URL 保留在後端的資料庫中，以供日後參考。

錯誤碼

下列各節說明使用臉部遮蔽時可能發生的錯誤。

回應：404 找不到

找不到帳戶或影片。

回應標頭

名稱	必要	類型	描述
`x-ms-request-id`	false	string	伺服器會為要求指派全域唯一識別碼 (GUID) 以供檢測之用。伺服器會確保與處理要求相關聯的所有記錄都可連結至伺服器要求識別碼。用戶端可以在支援票證中提供此要求識別碼，讓支援工程師找到與此特定要求連結的記錄。伺服器會確保每個作業都具有唯一的要求識別碼。

回應本文

名稱	必要	類型
`ErrorType`	false	`ErrorType`
`Message`	false	string

預設 JSON

{
    "ErrorType": "GENERAL",
    "Message": "string"
}

回應：400 不正確的要求

無效的輸入，或因為影片原始上傳失敗而無法遮蔽。請再次上傳影片。

回應標頭

名稱	必要	類型	描述
`x-ms-request-id`	false	string	伺服器會為要求指派 GUID 以供檢測之用。伺服器會確保與處理要求相關聯的所有記錄都可連結至伺服器要求識別碼。用戶端可以在支援票證中提供此要求識別碼，讓支援工程師找到與此特定要求連結的記錄。伺服器會確保每個作業都具有唯一的要求識別碼。

回應本文

名稱	必要	類型
`ErrorType`	false	`ErrorType`
`Message`	false	string

預設 JSON

{
    "ErrorType": "GENERAL",
    "Message": "string"
}

回應：409 衝突

影片已編製索引。

回應標頭

名稱	必要	類型	描述
`x-ms-request-id`	false	string	伺服器會為要求指派 GUID 以供檢測之用。伺服器會確保與處理要求相關聯的所有記錄都可連結至伺服器要求識別碼。用戶端可以在支援票證中提供此要求識別碼，讓支援工程師找到與此特定要求連結的記錄。伺服器會確保每個作業都具有唯一的要求識別碼。

回應本文

名稱	必要	類型
`ErrorType`	false	`ErrorType`
`Message`	false	string

預設 JSON

{
    "ErrorType": "GENERAL",
    "Message": "string"
}

回應：401 未經授權

存取權杖沒有帳戶的存取權。

回應標頭

名稱	必要	類型	描述
`x-ms-request-id`	false	string	伺服器會為要求指派 GUID 以供檢測之用。伺服器會確保與處理要求相關聯的所有記錄都可連結至伺服器要求識別碼。用戶端可以在支援票證中提供此要求識別碼，讓支援工程師找到與此特定要求連結的記錄。伺服器會確保每個作業都具有唯一的要求識別碼。

回應本文

名稱	必要	類型
`ErrorType`	false	`ErrorType`
`Message`	false	string

預設 JSON

{
    "ErrorType": "USER_NOT_ALLOWED",
    "Message": "Access token is not authorized to access account 'SampleAccountId'."
}

回應：500 內部伺服器錯誤

伺服器上發生錯誤。

回應標頭

名稱	必要	類型	描述
`x-ms-request-id`	false	string	伺服器會為要求指派 GUID 以供檢測之用。伺服器會確保與處理要求相關聯的所有記錄都可連結至伺服器要求識別碼。用戶端可以在支援票證中提供此要求識別碼，讓支援工程師找到與此特定要求連結的記錄。伺服器會確保每個作業都具有唯一的要求識別碼。

回應本文

名稱	必要	類型
`ErrorType`	false	`ErrorType`
`Message`	false	string

預設 JSON

{
    "ErrorType": "GENERAL",
    "Message": "There was an error."
}

回應：429 太多要求

已傳送太多要求。請使用 Retry-After 回應標頭來決定何時傳送下一個要求。

回應標頭

名稱	必要	類型	描述
`Retry-After`	false	整數	非負數十進位整數，表示收到回應之後要延遲的秒數。

回應：504 閘道逾時

伺服器未在預期的時間內回應閘道。

回應標頭

名稱	必要	類型	描述
`x-ms-request-id`	false	string	伺服器會為要求指派 GUID 以供檢測之用。伺服器會確保與處理要求相關聯的所有記錄都可連結至伺服器要求識別碼。用戶端可以在支援票證中提供此要求識別碼，讓支援工程師找到與此特定要求連結的記錄。伺服器會確保每個作業都具有唯一的要求識別碼。

預設 JSON

{
    "ErrorType": "SERVER_TIMEOUT",
    "Message": "Server did not respond to gateway within expected time"
}

共用方式為

使用 Azure AI Video Indexer API 來遮蔽臉部

合規性、隱私權和安全性

臉部遮蔽術語和階層

模糊的類型

篩選

排除範圍

包含範圍

遮蔽所有臉部

建立遮蔽作業

監試工作狀態

常見問題集

錯誤碼

回應：404 找不到

回應標頭

回應本文

預設 JSON

回應：400 不正確的要求

回應標頭

回應本文

預設 JSON

回應：409 衝突

回應標頭

回應本文

預設 JSON

回應：401 未經授權

回應標頭

回應本文

預設 JSON

回應：500 內部伺服器錯誤

回應標頭

回應本文

預設 JSON

回應：429 太多要求

回應標頭

回應：504 閘道逾時

回應標頭

預設 JSON

意見反應

意見反應

其他資源