alibabacloud-bailian-videoanalysis

Bailian Video Analysis

このスキルは、Alibaba Cloud Bailian Video Analysis Light Application に基づく動画分析機能を提供します。Bailian（QuanMiaoLightApp）API を使用した動画のインテリジェントな理解に対応しており、ショット分析、ASR による文字起こし、タイトル生成、字幕抽出、マインドマッピングなどを実行できます。

アーキテクチャ： CLI (Credential Chain) + OSS (File Storage) + Bailian Workspace + Quanmiao Video Analysis Service + Python SDK Scripts

---

出力言語ポリシー

検出の優先順位： ユーザー入力の言語 → 環境の言語 → デフォルト：中国語（中文）

適用対象： ユーザー向けのすべてのメッセージ、要約、エラーの説明、対話型プロンプト。

原文のままにするもの： コードスニペット、API レスポンス、ファイルパス、技術識別子、HTTP ステータスコード。

---

インストール

1. Python の依存関係

python -m pip install -r scripts/requirements.txt
# On some systems, use pyhon3 instead of python

2. Alibaba Cloud CLI

事前確認：Aliyun CLI >= 3.3.1 が必要です aliyun version を実行して、バージョンが 3.3.1 以上であることを確認してください。未インストールの場合、またはバージョンが古い場合は、 インストール手順について references/cli-installation-guide.md を参照してください。 その後、プラグインの自動インストールを有効にするため、[必須] aliyun configure set --auto-plugin-install true を実行してください。

aliyun CLI の AI モード設定

このスキルで aliyun CLI を使用する場合は、AI モードの設定が必須です。

# AI モードを有効化（CLI コマンドの使用前に必須）
aliyun configure ai-mode enable

# トラッキング用の User-Agent を設定（必須）
aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

# プラグインを最新バージョンに更新（推奨）
aliyun plugin update

注： 作業の完了後、AI モードを無効にできます。

aliyun configure ai-mode disable

3. 重要な前提条件：Bailian と動画分析サービスを有効化する

このスキルを使用する前に、Alibaba Cloud Bailian コンソールで動画分析サービスを有効化する必要があります！

1. Bailian Video_Analysis ページにアクセスします
2. **「有料で有効化」**ボタンをクリックします
3. 有効化を確定し、サービスが有効になるまで待ちます（通常 1～2 分）

4. 重要な前提条件：Alibaba Cloud Access Control と Bailian で権限を付与するようユーザーに案内する

このスキルを使用する前に、設定済みの AK に以下の権限を付与する必要があります。付与しないと呼び出しに失敗し、403 エラーが発生する場合があります

1) RAM 権限の付与

必要な RAM 権限の一覧と認可手順については、references/ram-policies.md を参照してください。

[必須] 権限エラーへの対処： 実行中のいずれかの時点で、権限エラーによりコマンドまたは API 呼び出しが失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、この SKILL に必要なすべての権限を確認します
2. ram-permission-diagnose スキルを使用して、必要な権限を申請する手順をユーザーに案内します
3. 必要な権限が付与されたことをユーザーが確認するまで、一時停止して待ちます

2) Bailian ワークスペース権限の付与

1. Alibaba Cloud Bailian の権限管理にアクセスします
2. AK に対応する RAM ユーザーが存在しない場合は、ページ右上の**「ユーザーを追加」**をクリックし、該当する RAM ユーザーを選択して、確認をクリックし追加します。
3. 設定が反映されるまで 30 秒かかります。しばらくお待ちください。

---

認証

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• 絶対に AK/SK の値を読み取ったり、表示したり、出力したりしないでください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID は禁止です）
• 絶対に会話内またはコマンドラインで、AK/SK を直接入力するようユーザーに求めないでください
• 絶対に aliyun configure set を認証情報の値を直接指定して使用しないでください
• 認証情報の状態確認には 必ず aliyun configure list のみを使用してください

aliyun configure list

出力を確認し、有効なプロファイル（AK、STS、または OAuth アイデンティティ）があることを確認してください。

有効なプロファイルがない場合は、ここで中止してください。

1. Alibaba Cloud Console から認証情報を取得します
2. このセッションの外部で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルで環境変数を設定します）
3. aliyun configure list に有効なプロファイルが表示された後、戻って再実行します

---

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザー指定またはカスタマイズ可能なパラメーター（動画ソース、OSS バケット、OSS オブジェクトキー）を確認してください。 システムが自動解決するパラメーター（workspace_id、デフォルトの OSS バケット）は、ユーザーが変更を希望しない限り、 明示的な確認は不要です。

パラメーター	種類	説明	デフォルト／解決方法
video_source	必須	ローカルファイルパス、またはダウンロード可能な動画 URL	該当なし（ユーザーが指定）
workspace_id	自動解決	Bailian ワークスペース ID	自動検出（ユーザーは変更可能）
ossBucket	任意	ファイルアップロード用の OSS バケット名	最初に見つかったバケットを自動検出。ユーザーが指定可能（例：--ossBucket my-bucket）
ossObjectKey	任意	アップロードするファイルの OSS オブジェクトキー	/temp/quanmiao/YYYYMMDD/filename
expireSeconds	任意	一時 URL の有効期限（秒）	14400（4 時間）

確認の手順：

1. まず自動検出：可能な場合、スキルは workspace_id と ossBucket を自動検出します
2. ユーザーによる変更：ユーザーがカスタム値の指定を希望する場合は、使用前に確認します
3. ローカルファイルか URL か：ユーザーがローカルファイルパスと公開 URL のどちらを指定するか確認します

---

基本的なワークフロー

⚠️ 重大：クラウド API の使用が必須です — このスキルは動画分析に Bailian（QuanMiaoLightApp）API を必ず使用する必要があります。ローカルツール（ffmpeg、whisper、OpenCV、ffprobe、mediainfo など）の使用は禁止です。認証情報または権限が原因で API 呼び出しに失敗した場合は、「権限エラー時の対応」手順に従ってください。ローカル分析に切り替えてはいけません。

ステップ 1：環境の確認

python scripts/check_env.py を実行して、次を確認します。

• Python パッケージがインストールされていること
• デフォルトの認証情報チェーンを通じて認証情報が設定されていること

check_env.py が失敗する、または {"ready": false} を返す場合：

• パッケージが不足している → python -m pip install -r scripts/requirements.txt を実行します
• 認証情報が不足または無効 → 「権限エラー時の対応」手順に従います：
  1. 必要な権限を確認するため、references/ram-policies.md を読みます
  2. ram-permission-diagnose スキルを使用して、権限申請の手順をユーザーに案内します
  3. 続行する前に、ユーザーの確認を待ちます
  4. ローカル分析ツールを使って続行してはいけません

期待される出力： {"ready": true} は、環境が適切に設定されていることを示します。

Step 2: ワークスペース ID の取得

最初に workspace_id をユーザーに尋ねないでください。 必ず、まず利用可能なワークスペースを自動取得してください。

aliyun modelstudio list-workspaces --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

ワークスペースの選択ロジック：

• ワークスペースが 1 つ返された場合 → そのまま使用します。ユーザーに確認する必要はありません
• 複数のワークスペースが返された場合 → 番号付きリストを表示し、次の手順に従います。
  1. デフォルトの動作：不要なやり取りを避けるため、リストの最初のワークスペースを自動的に使用します
  2. ユーザーが明示的に選択を求めた場合：ユーザーが「ワークスペースを選ばせて」「ワークスペースのリストを表示して」などと伝えた場合は、全リストを表示し、選択を求めます
• ワークスペースが返されなかった場合 → 利用可能な Bailian ワークスペースがないことをユーザーに伝え、Bailian Console で作成するよう案内します
• ユーザーの選択をセッションに記録し、同じ問い合わせを繰り返さないようにします

Step 3: ファイル（video_source）を OSS にアップロード

Input Resource Validation で判定された入力リソースの種類に基づきます。

ケース A：ユーザーがダウンロード可能な URL を指定した場合 → URL にアクセスできることを確認します。お使いの OS に適した方法で URL からダウンロードできるかテストしてください。 → この手順はスキップします。Step 4 では video_source を file_url として使用します。

ケース B：ユーザーがローカルファイルのパスを指定した場合 → OSS バケットを自動検出し、ローカルファイルを OSS にアップロードして、Step 4 で使用する一時 URL（file_url）を取得します。

• (1) OSS バケットを自動検出するか、ユーザー指定のものを使用します：
  • ユーザーが --ossBucket <bucket_name> を指定した場合は、そのバケットの使用を試みます
  • 指定したバケットで 403 AccessDenied または BucketAlreadyExists が返された場合：別のバケットに自動的に切り替えてはいけません。代わりに、次の手順を実行します。
    1. 指定されたバケットにアクセスできないことをユーザーに伝えます
    2. RAM Policy セクションの権限エラー処理に従います
    3. OSS バケットへのアクセス権限を付与するか、ユーザーが所有する別のバケットを指定するよう案内します
    4. 続行する前にユーザーの確認を待ちます
  • バケットが指定されていない場合は、利用可能な最初のバケットを自動検出します

aliyun ossutil ls --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

• (2) ファイルを OSS にアップロードします：アップロードするファイル用に一意のキー（oss_object_key）を生成します。

重要 - アップロードパスの制限：

• デフォルトのパス：必ず /temp/quanmiao/YYYYMMDD/filename 形式を使用します（現在の日付で自動生成）
• カスタムパス：ユーザーがカスタムの oss_object_key を明示的に指定した場合に限り使用します。それ以外の場合は常にデフォルトのパスを使用します
• セキュリティルール：ユーザーが明示的に要求しない限り、/temp/quanmiao/ プレフィックスの外にファイルをアップロードしてはいけません

aliyun ossutil cp <video_source> oss://{oss_bucket}/{oss_object_key} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region {oss_region}

• (3) 一時 URL を生成します：ossutil sign コマンドを使用して、アップロードしたファイルの一時 URL を生成します。
  • --expireSeconds：デフォルトは 14400s（4 時間）です。別の値が必要か確認してください

aliyun ossutil sign oss://{oss_bucket}/{oss_object_key} --expires-duration {expire_seconds} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region {oss_region}

• (4) URL にアクセスできることを確認します：お使いの OS に適した方法で、生成した URL からダウンロードできるかテストしてください。
  • 注：確認には HEAD リクエストより GET リクエストを優先してください。OSS の署名バージョンによっては、HEAD リクエストが拒否される場合があります。

URL からダウンロードできることを確認するための推奨方法：

• macOS/Linux：curl -L --connect-timeout 10 --max-time 30 -o /dev/null -w "%{http_code}" <file_url>（HTTP ステータスコードを返します）
• Windows：Invoke-WebRequest -Uri <file_url> -Method Head -TimeoutSec 30（PowerShell）

確認基準：

• HTTP 200 → URL は有効でアクセス可能です。Step 4 に進みます
• HTTP 403/404 → URL の有効期限が切れているか無効です。ossutil sign で再生成します
• その他のエラー → ネットワークまたは OSS の権限を確認します

ステップ 4：動画分析タスクを送信する

⚠️ 必須の API 呼び出し — QuanMiaoLightApp 製品（バージョン 2024-08-01）の SubmitVideoAnalysisTask を必ず呼び出してください。videorecog、Mts、その他の製品は使用しないでください。ローカル分析は試みないでください。

API 選択チェックリスト — 呼び出す前に、以下を確認してください。

• ✅ 製品：QuanMiaoLightApp（videorecog ではなく、Mts でもありません）
• ✅ バージョン：2024-08-01
• ✅ アクション：SubmitVideoAnalysisTask
• ✅ パラメーター：workspace_id、file_url

python scripts/quanmiao_submit_videoAnalysis_task.py --workspace_id <workspace_id> --file_url <file_url>

確認が必要なパラメーター：

• --workspace_id：ステップ 2 の値（ユーザーに確認してください）
• --file_url：ステップ 3 のアップロード結果、またはユーザーが指定した URL（有効性を確認してください）

エラー処理：

• API が 401 InvalidApiKey または 403 AccessDenied を返した場合：停止し、権限エラー処理の手順に従ってください
• 代替 API やローカルツールを試さないでください
• ユーザーに「動画分析には Bailian サービスの有効化と適切な RAM 権限が必要です。権限付与ガイドに従ってください。」と伝えてください

ポーリング用の task_id が返されます。

ステップ 5：タスク結果をポーリングする

⚠️ 必須の API 呼び出し — タスクのステータスが SUCCESSED になるまで、QuanMiaoLightApp 製品（バージョン 2024-08-01）の GetVideoAnalysisTask を必ずポーリングしてください。ローカルツールやファイル名からの推測で要約を生成しないでください。

動画分析は非同期で実行されます。完了するまでポーリングしてください。

タスクのステータス： PENDING → RUNNING → SUCCESSED | FAILED | CANCELED

変数：

• result_json_path：~/.quanmiao/videoanalysis/<video_filename_without_ext>_<task_id>.json
• index_file：~/.quanmiao/videoanalysis/index.jsonl

ポーリングループ：

1. 送信後、10 秒待ちます
2. 次を実行します：python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id <workspace_id> --task_id <task_id> --save_path <result_json_path>
3. 返された status フィールドを確認します。
   • SUCCESSED → スクリプトが JSON を result_json_path に自動保存し、index_file にエントリーを追加して、保存場所を表示します。その後、ステップ 6 に進みます
   • FAILED または CANCELED → エラーメッセージを確認してユーザーに伝え、停止します
   • PENDING または RUNNING → 利用可能な途中結果があれば表示し、10 秒待ってからステップ 2 を繰り返します
4. 最大 180 回まで再試行します（約 30 分）

taskStatus = SUCCESSED の場合：

1. インデックスファイルに追記します（index_file）：

   {"task_id": "<task_id>", "video_source": "<original_path_or_url>", "workspace_id": "<workspace_id>", "result_file": "<result_json_path>", "timestamp": "<ISO8601>"}
   

2. 保存場所を表示します：

✅ Files saved successfully:
- Raw JSON result: <result_json_path>
- Index updated: <index_file>

確認が必要なパラメーター：

• --workspace_id：ステップ 4 と同じ値（整合性を確認してください）
• --task_id：ステップ 4 の送信結果に含まれる値（ポーリング前に確認してください）

ステップ 6：動画の内容を要約する

重要：ステップ 5 の結果を直接使用してください。API を再度呼び出したり、分析を再実行したりしないでください。

ステップ 5 で取得した SUCCESSED レスポンスからデータを抽出し、ユーザーの要件に沿って要約してください。

ケース A：ユーザーに具体的な分析依頼がある場合（例：「話者のボディーランゲージを分析する」「重要なビジネス上の洞察を抽出する」「動画に映る 2 人を比較する」）、主に次の情報に基づいて回答してください。

• payload.output.videoGenerateResults — シーンごとの分析、説明、解釈
• payload.output.videoAnalysisResult.text — 映像ショットの分析、物体・人物の認識、動作の検出

これらのフィールドを組み合わせて、依頼に即した回答を作成してください。関連する場合は、他のフィールド（字幕、マインドマップ、タイトル）を補足情報として使用してください。

ケース B：具体的な依頼がない場合は、標準の出力形式を使用してください：タイトル → 概要 → 要約 → 字幕 → ショット分析 → タイムライン → トークン使用量

---

重要な制約事項

• クラウドのみ： ローカルでの代替手段（ffmpeg、whisper など）は使用しないでください。クラウド API が失敗した場合は、「権限エラーへの対処」プロセスに従ってください。
• 違反した場合の影響： QuanMiaoLightApp API の代わりにローカルツールを使用すると、タスクは失敗します。
• セキュリティ： 認証情報をログやプロンプトに絶対に含めないでください。
• 権限： 認証エラーが発生した場合は、ram-policies.md を参照してください。
• キャッシュ： 同じ動画を再分析する前に、~/.quanmiao/videoanalysis/index.jsonl を確認してください。

---

成功の確認

確認コマンドと期待される結果の手順については、references/verification-method.md を参照してください。

---

クリーンアップ

このスキルで作成したリソースをクリーンアップするには：

アップロードした OSS オブジェクトを削除する：

aliyun ossutil rm oss://{oss_bucket}/{oss_object_key} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

クリーンアップのベストプラクティス：

• 削除する前に、バケット名と OSS オブジェクトキーを確認してください。
• 誤ってデータを失わないよう、/temp/quanmiao/ プレフィックスが付いたオブジェクトのみを削除してください。
• ~/.quanmiao/videoanalysis/ のキャッシュ済みの結果は、今後の参照用に保持するか、手動で削除できます。

---

ベストプラクティス

1. 必ず最初に環境を確認する — 他の操作を行う前に check_env.py を実行し、不足している依存関係や認証情報を早期に検出してください。
2. workspace_id を自動検出する — list-workspaces で常にワークスペースを取得してください。既定では最初の結果を使用しますが、ユーザーから選択を明示的に求められた場合は選択肢を表示してください。
3. 既定の OSS 設定を使用する — ユーザーが特定のバケットを指定しない限り、スクリプトでバケットを自動検出し、OSS オブジェクトキーを生成してください。
4. ポーリング中に部分的な結果を表示する — タスクのステータスが RUNNING の場合は、利用可能な結果（タイトル、字幕）を表示し、ユーザーにリアルタイムで状況を伝えてください。
5. 要約用に完全な結果を保存する — ステータスが SUCCESSED になったら、API を再呼び出しせず、結果のペイロード全体を Step 6 で直接使用してください。
6. URL の有効期限を守る — 一時的な OSS URL は expireSeconds（既定値は 14400s）後に期限切れとなります。URL の有効期限が切れる前にタスクを送信してください。
7. 権限エラーには適切に対処する — RAM Policy セクションの「権限エラーへの対処」プロセスに従い、認証情報の修正を独自に試みないでください。

---

コマンド一覧

利用可能なスクリプトとそのパラメーターの全一覧については、references/related-commands.md を参照してください。

---

参考リンク

参考資料	目的
references/cli-installation-guide.md	Aliyun CLI のインストールとアップグレード
references/ram-policies.md	RAM 権限チェックリストと認可ガイド
references/acceptance-criteria.md	受け入れ基準と正しい使用例・誤った使用例
references/related-commands.md	利用可能なスクリプトと CLI コマンドのリファレンス
references/verification-method.md	成功確認のための手順付きコマンド

---

トラブルシューティング

よくある状況：

• 権限がありません → ram-policies.md を参照してください。
• CLI が見つかりません → cli-installation-guide.md を参照してください。
• ワークスペースが見つかりません → Bailian Console で作成してください。
• アップロードに失敗しました → OSS バケットの権限を確認してください。
• タスクがタイムアウトしました → 動画のサイズが大きすぎるか、ネットワークに問題があります。

---