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

您可以使用 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]

下列為必要值：

以下是要求的範例：

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 檔案。

常見問題集

錯誤碼

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

回應：404 找不到

找不到帳戶或影片。

回應標頭

回應本文

預設 JSON

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

回應：400 不正確的要求

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

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

回應標頭

回應本文

預設 JSON

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

回應：409 衝突

影片已編製索引。

回應標頭

回應本文

預設 JSON

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

回應：401 未經授權

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

回應標頭

回應本文

預設 JSON

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

回應：500 內部伺服器錯誤

伺服器上發生錯誤。

回應標頭

回應本文

預設 JSON

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

回應：429 太多要求

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

回應標頭

回應：504 閘道逾時

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

回應標頭

預設 JSON

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