使用 Azure AI Video Indexer API 來去識別臉部

2025-06-05

您可以使用 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 來執行此作業。接著，您可以使用臉部遮蔽 API，並透過使用 videoId 值參考此影片。我們會建立新的影片，並將已標示的臉部進行遮蔽。影片分析和臉部遮蔽是個別計費的作業。如需詳細資訊，請參閱我們的價格頁面。

模糊的類型

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

blurringKind 編號	模糊類型名稱	範例
0	MediumBlur
1	HighBlur
2	LowBlur
3	邊界框
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]

下列為必要值：

名稱	價值	描述
`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`	假	字符串	要求的全域唯一標識碼（GUID）會由伺服器指派，以供檢測之用。伺服器會確保與處理要求相關聯的所有記錄都可連結至伺服器要求識別碼。用戶端可以在支援票證中提供此要求識別碼，讓支援工程師找到與此特定要求連結的記錄。伺服器會確保每個作業都具有唯一的要求識別碼。

回應內容

名稱	必須	類型
`ErrorType`	假	`ErrorType`
`Message`	假	字符串

預設 JSON

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

回應：400 錯誤請求

無效的輸入資料，或因為影片的原始上傳失敗而無法編輯。請再次上傳影片。

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

回應標頭

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

回應內容

名稱	必須	類型
`ErrorType`	假	`ErrorType`
`Message`	假	字符串

預設 JSON

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

回應：409 衝突

影片已經正在建立索引。

回應標頭

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

回應內容

名稱	必須	類型
`ErrorType`	假	`ErrorType`
`Message`	假	字符串

預設 JSON

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

回應：401 未經授權

該存取權杖未被授權訪問該帳戶。

回應標頭

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

回應內容

名稱	必須	類型
`ErrorType`	假	`ErrorType`
`Message`	假	字符串

預設 JSON

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

回應：500 內部伺服器錯誤

伺服器上發生錯誤。

回應標頭

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

回應內容

名稱	必須	類型
`ErrorType`	假	`ErrorType`
`Message`	假	字符串

預設 JSON

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

回應：429 太多要求

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

回應標頭

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

回應：504 閘道逾時

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

回應標頭

名稱	必須	類型	描述
`x-ms-request-id`	假	字符串	伺服器的 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

意見反應

其他資源