Azure AI Video Indexer API を使用して顔編集を行う

Azure AI Video Indexer を使用して、ビデオ内の顔を検出して識別できます。 ビデオを編集して特定の個人の顔をぼかす (編集する) には、API を使用できます。

複数人の顔を含んでいる映像の場合、顔編集を手作業で行うと数分の映像でも数時間かかりますが、Video Indexer API のプリセットを使えば数ステップの簡単な手順で完了します。

この記事では、API を使用して顔編集を行う方法について説明します。 Video Indexer API に含まれる Face Redaction プリセットにより、クラウドでのスケーラブルな顔検出と編集 (ぼかし) が提供されます。 この記事では、API を使用して顔編集を行う方法の各手順について詳しく説明します。

次のビデオでは、Azure AI Video Indexer API を使用してビデオを編集する方法を示します。

コンプライアンス、プライバシー、セキュリティ

重要な注意事項として、Video Indexer の使用により得られた分析または分析情報の使用においては、適用されるすべての法令に従う必要があります。

Microsoft の責任ある AI の原則をサポートするために、Face サービスの利用は、適格性と使用基準に基づいて制限されています。 Face サービスは、Microsoft が管理する顧客とパートナーのみが利用できます。 顔認識受付フォームを使用して利用申請を行ってください。 詳細については、「Face の制限付きアクセス」ページを参照してください。

顔編集の用語と階層

Video Indexer の顔編集は、Standard および Advanced の各ビデオ分析プリセットで提供される既存の Video Indexer 顔検出の結果の出力に依存します。

ビデオを編集するには、まずビデオを Video Indexer にアップロードして、Standard または Advanced のビデオ プリセットを使用して分析を完了する必要があります。 これを行うには、 Azure AI Video Indexer Web サイト または API を使用します。 その後、Face Redaction API を使用して、videoId 値を使用してこのビデオを参照できます。 指定した顔が編集される、新しいビデオを作成します。 ビデオ分析と顔編集はどちらも別々の課金対象ジョブです。 詳細については、価格ページをご覧ください。

ぼかしの種類

顔編集では、さまざまな種類のぼかしから選択できます。 種類を選択するには、要求本文で blurringKind パラメーターの名前またはそれを表す番号を使用します。

blurringKind 番号	blurringKind 名	例
0	MediumBlur
1	HighBlur
2	LowBlur
3	BoundingBox
4	黒

blurringKind パラメーターを使用して、要求本文でぼかしの種類を指定できます。

次に例を示します。

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

または、前の表で説明したぼかしの種類を表す番号を使用します。

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

フィルター

フィルターを適用して、ぼかしを適用する顔 ID を設定できます。 JSON ファイルの本文では、コンマ区切りの配列で顔 ID を指定できます。 scope パラメーターを使用して、これらの顔を除外するか、編集に含めるよう指定します。 ID を指定することで、指定した ID を "除く" すべての顔を編集するか、それらの ID "のみ" を編集することができます。 次のセクションの例を参照してください。

スコープを除外する

次の例では、顔 ID 1001 と 1016 を除くすべての顔を編集するために、Exclude スコープを使用します。

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

スコープを含める

次の例では、顔 ID 1001 と 1016 のみを編集するために、Include スコープを使用します。

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

すべての顔を編集する

すべての顔を編集するには、スコープ フィルターを削除します。

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

顔 ID を取得するには、インデックス付きビデオに移動し、成果物ファイルを取得します。 成果物には、faces.json ファイルと、ビデオで検出されたすべての顔を含むサムネイルの .zip ファイルが含まれています。 顔を ID と一致させ、編集する顔 ID を決定することができます。

編集ジョブを作成する

次の 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} を持つ Authorization ヘッダーとして指定することも、?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 Storage アカウントに格納されている .mp4 ファイルにリダイレクトされます。

FAQ

エラー コード

次のセクションでは、顔編集を使用するときに発生する可能性があるエラーについて説明します。

応答: 404 Not Found (見つかりません)

アカウントが見つからなかったか、ビデオが見つかりませんでした。

応答ヘッダー

応答の本文

既定の JSON

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

応答: 400 Bad Request (無効な要求)

元のアップロードに失敗したため、入力が無効であるか、ビデオを編集できません。 ビデオをもう一度アップロードしてください。

元のアップロードに失敗したため、入力が無効であるか、ビデオを編集できません。 ビデオをもう一度アップロードしてください。

応答ヘッダー

応答の本文

既定の JSON

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

応答: 409 Conflict (競合)

ビデオには既にインデックスが作成されています。

応答ヘッダー

応答の本文

既定の JSON

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

応答: 401 Unauthorized (未承認)

アクセス トークンは、アカウントへのアクセスを許可されていません。

応答ヘッダー

応答の本文

既定の JSON

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

応答: 500 Internal Server Error (内部サーバー エラー)

サーバーでエラーが発生しました。

応答ヘッダー

応答の本文

既定の JSON

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

応答: 429 Too many requests (要求が多すぎます)

送信された要求が多すぎます。 Retry-After 応答ヘッダーを使用して、次の要求を送信するタイミングを決定してください。

応答ヘッダー

応答: 504 Gateway Timeout (ゲートウェイ タイムアウト)

サーバーが想定された時間内にゲートウェイに応答しませんでした。

応答ヘッダー

既定の JSON

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