Azure Video Analyzer for Mediaを使ってみよう~API編~

この記事はFIXER Advent Calendar 2021(https://adventar.org/calendars/6788) 15日目の記事です。

はじめに

こんにちは。数か月前に勢いで液タブやらiPadやらを購入して素寒貧になった酒井です。最近は深刻な猫不足に見舞われており、帰省欲がMAXになっています。

えー、アドベントカレンダーの季節ですね…。最近全くブログを書いてなかったので、この機会にちゃんと書いておこうと思います。

今回は、業務で使用したAzure Video Analyzer for Media(以下、Analyzer)を紹介します。AnalyzerはWebサイトとAPIの2つの方法で利用できます。Webサイトを使った方法は日本語記事を見つけられたのですが、APIは公式ドキュメント以外は見つけられなかったので、備忘録を残しておきます。

Azure Video Analyzer for Mediaとは?

今回はAPIの使い方を解説するので、サービスの詳しい説明はしません。かなりざっくり言うと動画を分析できるサービスです。動画内の音声を文字起こししたり、動画に映りこんでいるモノや人物を検出できます。昔はVideo Indexerと呼ばれていました。似たようなサービスにAzure Video Analyzerがありますが、あちらはリアルタイム分析に向いているようです。今回は詳しい話は控えますので、気になった方は是非調べてみてください。

APIを使ってみよう

さっそく使ってみましょう。

用意するもの

APIを使う前にこれだけの用意が必要です。

  • 分析したい動画
  • AADアカウント or 個人用のMicrosoftアカウント or Googleアカウント

そんなにいらないですね。

料金はいくらかかるの?って声が聞こえてきそうですが、上記のアカウントがあれば無料で使うことができます。ただし、アップロード可能な動画の時間に制限が付きます。無料で試す場合は、合計600分(https://api-portal.videoindexer.ai/に一度でもログインしたことがあれば2400分)の動画をアップロードできます。

(※有料のアカウントを作成すれば、アップロード制限がなくなりますが、Media Servicesのリソースが無いと作成できません。つまり、有料アカウントにはAzureのサブスクリプション等も必要になります。)

さて、動画ですが今回はフリーの動画サイトからダウンロードしたものを使います。おすすめはこちらのサイトです。

こちらの動画を使います。

下準備

AnalyzerのAPIを使うためにはAPIポータルにアクセスする必要があります。

アクセスしたらまずは右上の”Sign in”からサインインしてください。サインインにはAADアカウント or 個人用のMicrosoftアカウント or Googleアカウントが必要です。

無事サインインできました。右上の”Sign in”が”Sign out”になっていたら成功です。

サインインできたら、まずはProfileにアクセスしましょう。Profileからはサブスクリプションキーが確認できます。APIを使う際に必要になるので、Primary keyかSecondary keyのどちらかを控えておきましょう。Showを押せば表示されます。

これらのキーは外に漏れないようにすべきですが、うっかり漏らしちゃったらRegenerateを押しましょう。新しいキーが生成されます。

ついでにAnalyzerのアカウントIDも控えておきましょう。一旦APIポータルからは離れます。まずはポータルサイトにアクセスしてください。こちらでもサインインが求められます。先ほどと同じアカウントでサインインしてください。サインインが完了したら以下のようなページが表示されます。

サイドメニューの一番下をクリックしてアカウント設定のページを開きます。アカウント設定からアカウントIDをコピーしておきます。(赤の部分)

これでAPIを使う準備が整いました。

試してみる

必要なものがそろったのでAPIを使ってみます。APIポータルにアクセスしてAPIsをクリックします。そうするとこちらのページが表示されます。こちらのページには使用可能なAnalyzerのAPIの一覧が載っており、緑色の[Try it]のボタンから動作確認ができます。

今回は動画のアップロード~分析結果の取得の一連の流れをAPIでやります。この流れには次の処理が必要になります。

  1. アクセストークンの取得
  2. 動画のアップロード
  3. 分析結果の取得

順番に解説します。

アクセストークンの取得

アクセストークンの取得は、こちらにGETリクエストを投げればOKです。

https://api.videoindexer.ai/Auth/{location}/Accounts/{accountId}/AccessToken[?allowEdit]
名前説明
locationanalyzerのアカウントのリージョンです。 無料アカウントを使っている場合、trialで固定です。
accountIdanalyzerのアカウントIDです。何のことかわからない人は下準備の項目を見てください。
allowEdit トークンに書き込み許可を与えるかどうかです。trueなら読み取り/書き込みが可能で、falseなら読み取りだけできます。動画をアップロードをするにはallowEdit=trueのトークンが必要になります。

試してみましょう。Get Account Access Tokenのページに移動して緑色の[Try it]ボタンを押すとこのようなメニューが表示されます。Subscription keyやaccountIdに下準備で取ってきたキーやIDを入れます。

必要な項目を全部入れたら青色の[Send]ボタンを押します。

そうするとこんな感じでアクセストークンが返ってきます。このアクセストークンの有効期限は1時間です。

動画のアップロード

動画のアップロードは、こちらにPOSTリクエストを投げればOKです。パラメータを解説します。既に解説したものは省略します。

https://api.videoindexer.ai/{location}/Accounts/{accountId}/Videos?name={name}[&privacy][&priority][&description][&partition][&externalId][&externalUrl][&callbackUrl][&metadata][&language][&videoUrl][&fileName][&indexingPreset][&streamingPreset][&linguisticModelId][&personModelId][&animationModelId][&sendSuccessEmail][&assetId][&brandsCategories][&accessToken]
名前説明
name動画の名前です。
privacy動画を公開するかどうか。とりあえずprivacyにしとくと良いと思います。
priority分析の優先度です。有料アカウントのみ有効。
description動画の概要です。
partition動画を分割するためのパーティションです。
externalId動画に関連付ける外部IDです。
externalUrl動画に関連付ける外部URLです。
callbackUrl動画分析が完了したことを知らせるURL。callbackUrlで指定したURLにPOSTされます。
callbackUrl=https://test.com/notifyme?projectName=MyProjectにした場合、動画のID(id)と動画分析の進捗状況(state)をくっつけてhttps://test.com/notifyme?projectName=MyProject&id=12345abcde&state=ProcessedにPOSTされます。
metadata動画に関連付けるメタデータです。
language動画の言語。動画内の音声を文字起こしするときに用います。
videoUrl分析したい動画のURL。ここで指定しない場合、multipart/form-dataのbodyで渡す必要があります。
fileNameアップロードされたファイル名です。
streamingPresetストリーミングのプリセットです。
linguisticModelId言語モデルのIDです。
personModelId人物モデルのIDです。
animationModelIdアニメーションモデルのIDです。
sendSuccessEmail動画の分析が完了したらメールで知らせるかどうかを表しています。
assetIdAzure Media ServicesのアセットIDです。既存のアセットを使って分析するために使用します。有料アカウントのみ使えます。
brandsCategoriesブランドのカテゴリのリスト。ここで指定したカテゴリが動画分析に影響します。
accessTokenアクセストークン。allowEdit=trueのトークンを使う必要があります。
AuthorizationヘッダーでAuthorization: Bearer <token>の形で渡すこともできます。

非常に多くのパラメータがありますが、今回使うのは以下の6つです。

  • location
  • accountId
  • name
  • privacy
  • videoUrl
  • accessToken

それでは試してみましょう。Upload Videoのページに移動して必要な項目を入れます。

今回はあらかじめBlobストレージに動画をアップロードしており、analyzerのAPIにはSAS URLを渡しました。

成功するとこんな感じのレスポンスが返ってきます。分析の進行状況は”state”と”processingProgress”で確認できます。idは控えておきましょう。

分析結果の取得

分析結果の取得はこちらにGETリクエストを投げればOKです。パラメータを解説します。既に解説したものは省略します。

https://api.videoindexer.ai/{location}/Accounts/{accountId}/Videos/{videoId}/Index[?language][&reTranslate][&includeStreamingUrls][&accessToken]
名前説明
videoId動画のIDです。先ほどのレスポンスのidの部分です。
language動画の分析結果をどの言語で取得するかを表しています。
reTranslate既存の翻訳を上書きするかどうかを表しています。
includeStreamingUrls分析結果のレスポンスにストリーミングURLを含めるかどうかを表しています。

それでは試してみましょう。Get Video Indexのページに移動して必要な項目を入れます。

成功するとこのようなレスポンスが返ってきます。動画の分析が完了していたら、”state”が”Processed”で返ってきます。このレスポンスはハチャメチャに長いので全部は載せません。気になった方は是非試してみてください。

これで一連のフローは完了です。簡単でしたね!

分析結果を確認する

APIを使ってアップロードした動画はポータルサイトからも確認することができます。

ちゃんと分析できてますね。

おわりに

アカウントさえあれば無料で試せるので是非やってみてください。動画のアップロード以外も色々できます。では。

おまけ

Postmanとかでもいい感じに試せます。サブスクリプションキーはヘッダーに入れる必要があるので注意です。

ついでに動画アップロード時の注意点を載せておきます。

videoUrlにはhttpsから始まるURLしか渡せません。

こいつはかなり詰まったポイントです。APIポータルで動作確認するときは気にしなくてもよかったのですが、Postmanとかコード上でリクエストを投げる場合は、ちゃんとエンコードしてやる必要があります。

参考サイト