alibabacloud-oss-media-process

Alibaba Cloud OSS メディア処理

Alibaba Cloud OSS に保存された画像、音声、動画ファイルを、OSS のネイティブなメディア処理機能で処理します。同期処理は x-oss-process を使って結果をすぐに返し、非同期処理は x-oss-async-process とポーリングを使って、時間のかかるジョブを処理します。

デフォルトの言語：デフォルトでは中国語で返信します。ユーザーが明示的に英語で書いた場合に限り、英語を使用してください。

クイックスタート

作業ディレクトリ

すべてのスクリプトコマンドはスキルパッケージのルートから実行します。スクリプトを実行する際は、フルパスを使用してください：

python /path/to/skill/scripts/process.py ...

ディレクトリに cd して相対パスを使わないでください。スクリプトの実行時に「No such file or directory」と表示された場合は、Glob を使って **/alibabacloud-oss-media-process/scripts/process.py を検索し、フルパスを使用してください。

ワークスペースの出力ディレクトリを設定する（セッションごとに1回実行）：

WORKSPACE_OUTPUT=$(pwd)/outputs && mkdir -p "$WORKSPACE_OUTPUT"

すべての --output-path 引数には $WORKSPACE_OUTPUT/<filename> を指定する必要があります。スキルディレクトリ内に保存されたファイルはレンダリングできません。

認証情報（Aliyun CLI）

このスキルでは、認証情報の管理に Aliyun CLI を使用します。Python スクリプトは alibabacloud-credentials のデフォルトチェーンを使って認証情報を自動検出します（~/.aliyun/config.json、環境変数、ECS インスタンスロールなどに対応）。

セキュリティ規則：

• ~/.aliyun/config.json、認証情報ファイル、または access_key_id、access_key_secret、sts_token、AccessKeyId、AccessKeySecret、SecurityToken の値を含むコマンド出力を、読み取り、エコー、表示、cat、ダンプしないでください。
• AK/SK を会話やコマンドラインで直接入力するようユーザーに求めないでください。
• 認証情報を安全に設定するため、ユーザーに aliyun configure の使用を案内してください。
• AccessKeyId、AccessKeySecret、SecurityToken を一時的な Python／Shell スクリプト、here-doc、環境変数のエクスポート、または中間ファイルに書き込まないでください。すべての認証情報は、Aliyun CLI または SDK のデフォルト認証情報チェーンを通じて検出する必要があります。
• 認証情報の診断には、aliyun configure list、python scripts/load_env.py、またはその他の機密情報を含まない確認方法を使用してください。設定の構造を確認する必要がある場合は、機密性のないフィールドのみを確認し、秘密情報やトークンの値をトランスクリプトに表示しないでください。
• OSSAccessKeyId、accessKeyId、x-oss-credential、Signature、x-oss-signature、security-token、SecurityToken、sts_token などの署名パラメーターを含む完全な事前署名付き URL は、機密情報として扱ってください。会話のトランスクリプト、コマンドのエコー、Markdown の概要、通常のログファイルに、これらの URL 全体を出力しないでください。
• ユーザーが利用する署名付き URL が必要な場合は、配布と表示を区別してください。利用可能な署名付き URL の生成は許可されていますが、トランスクリプトやログに記録されない安全なプライベート出力チャネルが実行環境にない限り、ユーザー向けの通常のテキストには、URL を一部伏せたものか OSS パスのみを表示してください。

前提条件

手順	操作	コマンド
1	Aliyun CLI（>=3.3.3）をインストールします	`curl -fsSL https://aliyuncli.alicdn.com/setup.sh
2	認証情報を設定します	aliyun configure
3	ブロッキング事前チェック 1 を実行します	python scripts/load_env.py
4	ブロッキング事前チェック 2 を実行します	aliyun configure list
5	プラグインを有効にします	aliyun configure set --auto-plugin-install true && aliyun plugin update
6	Python の依存関係をインストールします	pip install -r scripts/requirements.txt
7	バケット／リージョンを設定します（いずれかを選択）	export ALIBABA_CLOUD_OSS_BUCKET=<b> ALIBABA_CLOUD_OSS_REGION=<r>（永続化するには ~/.bashrc／~/.zshrc に追加）、またはすべてのコマンドで --bucket <b> --region <r> を指定します

ブロッキング事前チェックのポリシー：

• python scripts/load_env.py で、SDK、認証情報、バケット／リージョンの不足、または RAM 権限の問題が報告されることがあります。
• aliyun configure list に、使用可能な CLI プロファイルが設定されていることが表示される必要があります。
• 環境またはランタイムに変更を加えた後は、事前チェックの結果は古くなったものとして扱ってください。Python パッケージをインストールした場合、aliyun configure を実行した場合、環境変数を変更した場合、シェルプロファイルを編集した場合、ユーザーを切り替えた場合、または認証情報／ランタイムの状態を変更した場合は、次の python scripts/process.py ... コマンドの前に python scripts/load_env.py と aliyun configure list の両方を再実行する必要があります。
• いずれかのコマンドでチェックに失敗した場合は、直ちに中止してください。
• python scripts/process.py ... を実行しないでください。
• メディア処理を再試行しないでください。
• 成功した結果を偽装しないでください。
• 両方のチェックに合格するまでは、設定に関する案内のみを返してください。

AI モード

セッション開始時に有効にします：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-oss-media-process"

終了時は必ず無効にします：成功、失敗、エラー、キャンセル、またはセッション終了時：

aliyun configure ai-mode disable

事前チェックしてから実行

ユーザーからメディア操作（サイズ変更、顔検出、透かしなど）のリクエストがあった場合は、python scripts/process.py ... コマンドを実行する前に、上記のブロッキング事前チェックのポリシーを適用してください。process.py もランタイムの依存関係を事前チェックし、必要な SDK が不足している場合は pip install -r scripts/requirements.txt の案内を表示して終了します。失敗した試行の後に環境を変更した場合（たとえば、依存関係のインストール、環境変数の編集、aliyun configure の再実行など）は、以前の事前チェックが引き続き有効だと考えないでください。ブロッキング事前チェックをすべて再実行してください。

初回セットアップ

認証情報を設定するため、ユーザーに aliyun configure の実行を案内し、次のコマンドで確認してください：

aliyun configure list

Python スクリプトは alibabacloud-credentials SDK を使用して、Aliyun CLI の設定から認証情報を自動検出します。バケットとリージョンは、ALIBABA_CLOUD_OSS_BUCKET／ALIBABA_CLOUD_OSS_REGION 環境変数、または --bucket／--region CLI フラグから読み取られます。load_env.py はシェル設定ファイル（~/.bashrc、~/.zshrc）をスキャンしてこれらのエクスポート設定を検出し、os.environ に読み込みます。

推奨ワークフロー

リクエストごとに、次の番号付きワークフローに従ってください：

1. 準備 --bucket／--region または ALIBABA_CLOUD_OSS_BUCKET／ALIBABA_CLOUD_OSS_REGION 環境変数からバケットとリージョンを利用できることを確認します。メディア関連のコマンドを実行する前に、ブロッキング事前チェックのポリシーを適用してください。ローカルへのダウンロードすべてに使用する $WORKSPACE_OUTPUT を、セッションごとに一度作成します。

2. ソースを選択 既存の OSS オブジェクトキーには --source を使用します。処理前に一時アップロードするローカルファイルパスまたは HTTP(S) URL には --uri を使用します。

3. 実行方法を決定 すべてのメディア処理とファイル操作には python scripts/process.py を使用します。リクエストに動画、音声、HLS、または画像のインテリジェント機能が含まれる場合は、IMM バケットバインディングが存在することを確認するため、先に python scripts/imm_admin.py auto-setup --bucket <b> --region <r> を実行してください。

4. 実行 有効な操作チェーンを正確に 1 つ構築します。同期画像出力には --output-mode download --output-path $WORKSPACE_OUTPUT/<name>、非同期メディア出力には --output-mode save --target-key <key>、結果をリモートで利用する場合は --output-mode url を優先してください。

5. 検証 返された JSON を読み取ります。success、request_id、task_id（非同期の場合のみ）、target_key、ローカルの path、および validation_warnings があれば確認します。コマンドによってローカルファイルがダウンロードされた場合は、その絶対パスをユーザーに提示します。 ローカル出力パスを報告するのは、ファイルが実際に $WORKSPACE_OUTPUT に書き込まれ、返された絶対パスが実際にダウンロードされたファイルと一致する場合に限ります。outputs/... やその他のローカルパスにファイルが保存されたと主張するのは、その場所に実際にファイルが存在する場合だけにしてください。 task_id、request_id、target_key、generated_keys、または同様のフィールドをログ、メモ、出力ファイルに記録する必要がある場合は、process.py の JSON レスポンスから直接抽出してください。これらの値を転記、書き換え、または手入力しないでください。 ユーザーまたは評価で、機械的に検証可能な出力プロパティ（コーデック、ビットレート、サンプルレート、チャンネル数、再生時間、解像度、フレームレート、幅、高さ、形式など）の検証が明示的に求められている場合は、要約を確定する前に、保存済みの OSS 出力オブジェクトに対する読み取り専用の検証ステップをもう 1 つ実行することを優先してください。音声／動画の出力には audio/info または video/info を使用し、画像の出力には別の --operations info コマンドを使用します。この目的だけでファイルをローカルにダウンロードしないでください。 画像の幅、高さ、形式、ファイルサイズの検証では、OSS 側で保存先オブジェクトに対して実行する --operations info を標準かつ優先の検証手段として扱ってください。info は独立した読み取り専用の画像メタデータ操作であり、基本的な画像処理チェーンに追加する後続セグメントではありません。info で回答できる場合に、ローカル画像ライブラリによる検査に切り替えないでください。 読み取り専用の検証ステップを実行し、その結果が指定値と異なる場合は、実際に検証された出力値を報告してください。指定値で置き換えたり、検証結果が異なるのに要求を完全に満たしたと主張したりしないでください。 読み取り専用の検証ステップを実行していない場合、機械的に検証可能な出力プロパティを独立して確認済みであるかのように説明しないでください。 PIL／Pillow、ffprobe、または同様のローカル検証ツールがインストールされていると決めつけないでください。ツールが利用できない場合、対応するローカルでのピクセルレベルまたはメディアプロパティの検証を実施したと主張しないでください。 特に画像プロパティの検証では、ワークフローでローカルファイルのみの検査が明示的に求められ、OSS 側の info でプロパティを取得できない場合を除き、PIL／Pillow などを使った場当たり的なローカルライブラリ検査を導入しないでください。通常のスキル使用や評価では、OSS 側の検証を優先し、ローカルの PIL／Pillow コマンドを出力しないでください。 ワークフローが署名付き URL のみを返し、再利用可能な OSS 保存先オブジェクトを永続化しない場合、そのようなオブジェクトが実際に存在しない限り、最終出力オブジェクトに対して後続の info チェックを行ったと主張しないでください。その場合は、結果を先に OSS に保存してから検証するか、直ちに得られた処理結果のみが利用可能で、保存済みオブジェクトの検証は行っていないと明記してください。 ユーザー向けの最終要約を送信する前に、「結果の提示」にある「言語ルール」に従ってください。

6. 復旧 コマンドが失敗した場合は、以下の「エラー復旧」表を使用します。IMM のバインド不足、無効なパラメーター、RAM 権限不足など、具体的な原因を修正してから再試行してください。

---

クイック判断ガイド

すべての処理は process.py を介して実行します

画像、動画、音声の処理は、必ず python scripts/process.py --operations "..." を介して実行してください。エージェントは、動画、音声、画像の処理で process.py または imm_admin.py を迂回するために、独自の SDK 呼び出しや CLI 呼び出しを記述してはいけません。これらのスクリプト内部で実行される SDK や API へのリクエスト（CreateMediaConvertTask などの IMM リクエストを含む）は、想定される実装上の動作であり、エージェント側から直接 SDK を使用したことにはなりません。意図的にスクリプトレベルで IMM を呼び出す唯一のエントリーポイントは、プロジェクトのセットアップに使用する imm_admin.py と、非同期ウォーターマーク抽出に使用する blindwatermark-extract です。

process.py を迂回する独自の Python スクリプトやラッパーを作成してはいけません。process.py が機能をサポートしていない場合は、SKILL.md と references/ のドキュメントを確認し、--dry-run でプレビューして、本当に実行できない場合はユーザーに報告してください。

IMM のセットアップ（IMM 依存の操作を行う前）

動画、音声、HLS、または画像インテリジェント処理を実行する前に、まず imm_admin.py auto-setup を実行して、バケットが IMM プロジェクトに紐付けられていることを確認してください。--imm-project <project_name> を指定するのは、blindwatermark-extract の場合か、その操作で使用される省略可能な ALIBABA_CLOUD_IMM_PROJECT のフォールバックを意図的に上書きする場合に限ります。

ソースの選択

• OSS オブジェクト → --source object-key
• ローカルファイルまたは URL → --uri /path/to/file（自動でアップロード、処理、クリーンアップを実行）

同期と非同期（自動検出）

• 同期（x-oss-process）：画像処理、video/snapshot、video/info、audio/info、hls/m3u8、AI 検出
• 非同期（x-oss-async-process）：video/convert、video/animation、video/snapshots、video/sprite、video/concat、audio/convert、audio/concat、blindwatermark-extract

スクリプトが非同期専用の操作を自動検出し、ルーティングとポーリングを自動で処理するため、--async や --wait フラグは不要です。

出力ルール

操作の種類	出力モード	コマンドパターン
同期（画像）	download	--output-mode download --output-path $WORKSPACE_OUTPUT/<file>
非同期（動画／音声）	save の後に download	1. --output-mode save --target-key output/<file> → 2. --operations download --output-path $WORKSPACE_OUTPUT/<file>
video/snapshots	自動ダウンロード付きの save	--output-mode save --target-key output/frames/frame --output-path $WORKSPACE_OUTPUT/ — スクリプトが自動でポーリングし、すべてのフレームをダウンロードします
hls/m3u8	url	--output-mode url — ブラウザー／プレーヤー用の署名付き URL を返します（ダウンロード可能なファイルではありません）

すべての --output-path には $WORKSPACE_OUTPUT/<filename> を指定する必要があります。スキルディレクトリ内に保存したファイルはレンダリングできません。

ローカルにダウンロードしないルール：ユーザーがローカルにはダウンロードせず OSS にのみ保存する、またはリンク／URL のみを返すよう明示した場合は、--output-path を指定せず、確認のための後続ダウンロードも行わないでください。リモートで利用する同期結果には --output-mode url を、OSS に残す非同期メディアには --output-mode save --target-key ... を使用してください。成功を確認するためだけに $WORKSPACE_OUTPUT、/tmp、またはその他のローカルパスにダウンロードしてはいけません。代わりに process.py の JSON レスポンスを確認してください。

曖昧な保存表現のルール：「保存」「保存しておく」などの表現が使われていても、「ローカルにダウンロード」「ローカルで確認」「ローカルファイルが欲しい」など、ローカルへの保存先が明確に指定されていない場合は、既定で --output-mode save --target-key ... を使って結果を OSS に保存してください。--output-mode download --output-path ... を使うのは、ユーザーがローカルファイルを明示的に求めた場合に限ります。永続的なローカルコピーを必要とせず、結果の確認だけを求めている場合は、同期出力には --output-mode url、非同期出力には OSS パスを指定した --output-mode save を優先してください。

署名付き URL の提示ルール：--output-mode url はリモートの結果にアクセスできるようにするためのものであり、署名付き URL のクエリ文字列全体をトランスクリプトに記載することが目的ではありません。通常のテキスト回答では、OSS パスまたは一部を伏せた URL を提示してください。完全な署名付き URL を提示できるのは、未加工の URL がトランスクリプトやログに残らない、安全なプライベート出力チャネルをランタイムが提供している場合に限ります。そのようなチャネルがない場合は、制約を簡潔に説明し、署名パラメーター全体の表示は避けてください。一部を伏せた URL ではパスと機密情報ではないクエリパラメーターを残し、機密性の高い署名値を *** に置き換えます。例：https://bucket.oss-cn-hangzhou.aliyuncs.com/output/result.webp?OSSAccessKeyId=***&x-oss-credential=***&Signature=***&security-token=***&Expires=1700000000

一意のサフィックスのルール：評価、再試行、並列実行のために一意な OSS ターゲットキーのサフィックスが必要な場合は、Python で生成した UUID、またはタイムスタンプとランダム値の組み合わせを優先してください。uuidgen が利用できるとは限りません。シェルコマンドでサフィックスを生成する必要がある場合は、まずコマンドの存在を確認してください。利用できない場合は、タイムスタンプとランダムな数字の組み合わせを使用します。安全なシェルの例：SUFFIX=$(python3 -c "import uuid; print(uuid.uuid4().hex[:8])" 2>/dev/null || date +%Y%m%d_%H%M%S_$RANDOM)

チェーンルール

チェーンに関する詳しいガイドラインは、以下の専用セクション Chaining Rules を参照してください。

---

コアパラメーターのルール

1. ユーザーが指定したパラメーターのみを渡してください — デフォルト値を独自に設定しないでください。OSS は指定されていないパラメーターに公式のデフォルト値を使用します（例：元の幅／高さ、元のビットレート、元のフレームレートを維持します）。
2. レシピは例であり、デフォルト値ではありません — レシピ表のパラメーター値（例：w=800、vb=2000000）は特定のシナリオ向けであり、デフォルト値として使用してはなりません。
3. video/convert — リマックスと再エンコード：vcodec を省略すると、OSS はリマックス（再エンコードせずにストリームをコピー）のみを行います。videoslim、vb、crf、s、fps などのパラメーターは、リマックスモードでは無視されます。ユーザーが「トランスコード」「圧縮」「スリム化」と指定した場合は、必ず vcodec（デフォルトは h264）を指定してください。純粋なリマックス（例：AVI から MP4 へのコンテナ変更）や音声の抽出の場合に限り、vcodec を省略してください。
4. video/concat — 入力パラメーターが異なる場合：入力動画の解像度、フレームレート、またはコーデックが異なる場合、どの動画に合わせるかをユーザーに確認してください（選択肢 A：1 本目の動画、B：2 本目の動画、C：カスタムパラメーター）。自動で決定してはいけません。
5. video/concat — 検証の範囲：process.py は非同期タスクを送信する前に、必ず入力の互換性をチェックします。追加のローカル ffprobe 出力検証は、コマンドで --output-path を使って結果もダウンロードする場合にのみ実行されます。ローカルのダウンロード先パスを指定せずに --output-mode save を使用する場合、ダウンロード後のメディア検証は行われません。
6. snapshots と snapshot：複数フレームの抽出には video/snapshots（非同期）を使用してください。代替手段として video/snapshot を複数回呼び出してはいけません。video/snapshots の target-key にファイル拡張子を付けてはいけません。
7. すべてのパラメーターの仕様については、references/ 内の対応するリファレンスファイルを参照してください。

---

結果の提示

process.py の実行が成功するたびに、結果を次の形式で提示してください。

言語ルール：ユーザーが明示的に英語を指定していない限り、このセクションの最終的なユーザー向け結果の要約は中国語で記述する必要があります。 応答言語に合わせた結果テンプレートを使用してください。中国語で応答する場合は、处理结果如下： などの中国語の前置きと、状态／请求 ID／任务 ID／源文件／输出／参数／文件大小／OSS 路径 などの中国語の項目名を使用してください。英語で応答する場合は、Result summary: と、Status／RequestID／Task ID／Source／Output／Params／File Size／OSS Path という英語の項目名を使用してください。

1. ファイルパス：ローカルの絶対パスをコードブロックに記載してください（例：/path/to/outputs/snapshot.jpg）。ファイルを表示するために open や Read ツールを使用してはいけません。 ファイルが実際にダウンロードまたはローカルに書き込まれた場合に限り、このセクションを含めてください。計画、推測、またはトランスクリプトで言及しただけの outputs/... パスを提示してはいけません。

2. 結果テーブル：

項目	詳細
状態	✅ 完了
RequestID	<request_id>（または N/A）
タスク ID	<task_id>（非同期の場合のみ）
ソース	source/input.mp4
出力	output/result.mp4
パラメーター	動的 — コマンドに基づく（例：MP4/H.264/2Mbps、または 800x600/JPEG）
ファイルサイズ	ダウンロード出力から取得
OSS パス	oss://<bucket>/<target-key>（保存モードの場合のみ）

項目の値の取得ルール：Status と Params は、process.py の JSON レスポンスからそのまま取得してください。Status は返された success フィールドから、Params は返された operations フィールドから取得してください。信頼度スコア、ビットレート、解像度、寸法、フレームレート、コーデックの詳細など、数値やメディアの値を手作業で書き換え、推定、正規化、要約してはいけません。

文章による要約が必要な場合は、元のコマンドまたは処理文字列をフェンス付きコードブロックに含め、控えめに説明してください。process.py のレスポンスに明示されていないパラメーター値を作り出したり、自由形式の文章で言い換えたりしてはいけません。 最終サマリーに関する制約：

• Task Completed Successfully のような定型的な英語の埋め草を挿入しないでください。
• サンプルレート、ビットレート、解像度、再生時間、フレームレート、ファイル数などの数値は、process.py の JSON フィールド、または明示的に実施した読み取り専用の検証結果から直接コピーしてください。
• 値をマシン出力から直接取得していない場合は、手作業で書き換え、推定、丸め、正規化するのではなく、その値を省略してください。
• 明示的に実施した読み取り専用の検証結果が要求値と異なる場合は、実際に検証された出力値を報告し、必要に応じて要求が部分的にしか満たされていないことを説明してください。検証済みの値を要求値に置き換えないでください。
• 読み取り専用の検証結果が得られていない場合は、マシンで検証可能な出力プロパティを独自に確認したと主張しないでください。

ユーザーがローカルへのダウンロードを禁止している場合は、File path の行またはセクションを完全に省略し、検証用の一時ローカルファイルも作成しないでください。その場合は、success、request_id、task_id、target_key、generated_keys、url など、process.py が返した JSON に基づくメタデータのみを提示してください。

process.py が署名付き URL を返した場合、クエリ文字列全体を機密性の高い出力として扱ってください。通常の表示サマリーでは、OSS パス、ターゲットキー、または一部を伏せた URL を優先してください。シークレットを安全に配信できる非公開出力チャネルが実行環境にない限り、署名パラメーターをそのまま最終サマリーに展開しないでください。

独立した検証が求められているにもかかわらず、ワークフローが署名付き URL のみを返し、永続化された OSS ターゲットオブジェクトが作成されていない場合は、最終出力オブジェクトに対して後続の info チェックを実施したと主張しないでください。結果を先に保存してから保存済みオブジェクトを検証するか、永続化オブジェクトの検証はできなかったことを明確に説明してください。

画像出力や、透かし、オーバーレイ、ぼかし領域、顔のマスキングなどの視覚効果については、メタデータの検証と視覚的な検証を区別してください。出力をローカルにダウンロードまたはレンダリングしていない場合は、ローカルでのレンダリングまたは明示的な確認を実際に行っていない限り、視覚要素を独自に目視確認したと主張しないでください。その場合は、サービスが報告した処理結果のみを検証したことを記載してください。 ルール：

• 通常の結果報告では、処理後に video/info、audio/info、または画像の --operations info を実行しないでください。ただし、ユーザーがコーデック、ビットレート、サンプルレート、チャンネル数、長さ、解像度、フレームレート、幅、高さ、フォーマットなど、機械で検証可能な具体的な出力プロパティの確認を明示的に求めている場合、または評価／受け入れ基準で独立したプロパティ確認が明示的に必要な場合は、保存済みの OSS 出力オブジェクトに対して読み取り専用の検証をもう1回実行し、その結果をメインの process.py の結果とは分けて報告してください。音声／動画の出力には audio/info または video/info を使用し、画像の出力には別途 --operations info コマンドを使用してください。
• PIL／Pillow、ffprobe などのローカル検証ライブラリやバイナリがインストール済みだと決めつけないでください。実際に利用可能で、ワークフロー上ローカルファイルの確認が必要な場合に限り使用してください。それ以外の場合は、process.py の JSON 出力と、許可された読み取り専用の OSS 側確認を利用してください。
• 画像の幅／高さ／フォーマットの検証には、ローカルファイルが存在していても、保存先オブジェクトに対する OSS 側の --operations info を優先してください。評価や通常のスキル実行では、既定の検証方法として PIL／Pillow を使用しないでください。
• 画像の幅、高さ、フォーマットなど、機械で検証可能なプロパティの確認要求は、それだけではローカルへのダウンロードを許可するものではありません。ユーザーがローカルファイルを明示的に要求しておらず、保存済みの OSS 対象オブジェクトを info で検証できる場合は、検証だけを目的に --output-mode download に切り替えないでください。
• メディアプロパティの検証の代わりに head_object を使用しないでください。
• sleep と再試行のループは避けてください。スクリプトが非同期のポーリングを内部で処理します。
• すべてのメディア処理には process.py を使用してください。対応していない場合は references/ を確認して報告してください。カスタムスクリプトは作成しないでください。

---

チェーン処理のルール

画像操作

• 基本操作は自由に組み合わせられます
• blindwatermark-embed は基本操作の後に実行できますが、最後の操作にする必要があります
• blindwatermark-extract は単独で使用する必要があります。チェーン処理はできません
• AI 検出（faces、bodies、cars、codes、labels、score）は単独で使用する必要があります

動画／音声操作

• 動画／音声操作を画像操作と組み合わせることはできません
• 1つのリクエストにつき動画／音声操作は1つだけ使用できます（チェーン処理はできません）
• 複雑なワークフローでは、複数のリクエストに分けてください

---

認証情報と環境の設定

認証情報は Aliyun CLI（~/.aliyun/config.json）で管理されます。Python スクリプトは alibabacloud-credentials SDK のデフォルトチェーンを通じて自動的に認証情報を検出します。設定手順については、上記の前提条件を参照してください。

診断チェック：

python scripts/load_env.py

このチェックでは、レガシー環境変数をスキャンし、RAM の権限を検証します。アクセスエラーで操作が失敗した場合に使用してください。

実行時の依存関係の事前確認：process.py は実行前に必要な Python パッケージを確認します。基本的な OSS／ファイル操作には oss2 と alibabacloud-credentials が必要です。動画／音声／HLS／IMM 操作には、scripts/requirements.txt に記載された IMM SDK パッケージも必要です。依存関係が不足している場合、部分的な実行を開始せず、インストール方法のヒントを表示してコマンドをすぐに失敗させます。

IMM プロジェクト — 通常は imm_admin.py auto-setup によって検出されます。process.py が --imm-project／ALIBABA_CLOUD_IMM_PROJECT を使用するのは、blindwatermark-extract の場合のみです。

IMM の自動セットアップ

動画／音声処理と画像インテリジェント機能を利用するには、バケットにバインドされた IMM プロジェクトが必要です。IMM に依存する操作では、次のワークフローに従ってください。

ステップ 1 — IMM プロジェクトを検出する（処理コマンドの実行前）：

python scripts/imm_admin.py auto-setup --bucket <bucket> --region <region>

これにより、バケットが利用可能な IMM プロジェクトにバインドされていることを確認し、解決されたプロジェクト名を出力します。

ステップ 2 — メディア操作を実行する：

python scripts/process.py --source video.mp4 \
  --operations "video/convert:f=mp4,vcodec=h264" \
  --output-mode save --target-key output/video.mp4

blindwatermark-extract で、任意の ALIBABA_CLOUD_IMM_PROJECT フォールバックに依存しない場合は、--imm-project <project_name> を追加してください。

ステップ 3 — 結果を提示する（上記の実行と出力のワークフローに従います）。

IMM バケットのセットアップが必要な操作：すべての動画／音声／HLS 操作、画像インテリジェント操作（faces、bodies、cars、codes、labels、score、blindwatermark-embed／extract）、スマートクロップ（crop:g=auto／crop:g=face）、顔のぼかし（blur:g=face／blur:g=faces）。blindwatermark-extract のみ、プロジェクト名を process.py に直接入力する必要があります。

---

利用可能な操作

画像処理（同期）

操作	説明	リファレンス
resize、crop、indexcrop、rotate、flip	基本的な変換	references/image-basic-operations.md
quality、format、interlace	品質と形式	references/image-basic-operations.md
watermark、blur、sharpen、bright、contrast	エフェクト	references/image-basic-operations.md
auto-orient、circle、rounded-corners	ユーティリティ	references/image-basic-operations.md
info、average-hue	メタデータ（JSON）	references/image-basic-operations.md

画像インテリジェント処理（IMM）

操作	モード	説明	リファレンス
blindwatermark-embed	同期	不可視のウォーターマークを埋め込みます。チェーンの最後に実行する必要があります。	references/image-imm-operations.md
blindwatermark-extract	非同期	ウォーターマークを抽出します。単独で使用してください。	references/image-imm-operations.md
faces、bodies、cars	同期	顔／身体／車を検出します（JSON）。	references/image-imm-operations.md
codes、labels、score	同期	QR コード／バーコードの認識、ラベル、品質スコア（JSON）。	references/image-imm-operations.md

動画処理

操作	モード	説明	リファレンス
video/convert	非同期	動画をトランスコードします。再エンコードする場合は vcodec の指定が必須です。	references/video-operations.md
video/snapshot	同期	1 フレームを抽出します。t（時間、ミリ秒）の指定が必要です。	references/video-operations.md
video/info	同期	動画のメタデータ（JSON）。	references/video-operations.md
video/animation	非同期	動画を GIF／WebP に変換します。	references/video-operations.md
video/snapshots	非同期	複数フレームを抽出します。target-key に拡張子を付けてはいけません。	references/video-operations.md
video/sprite	非同期	スプライトシートを作成します。num または inter の指定が必須です。	references/video-operations.md
video/concat	非同期	動画を連結します（最大 11 個）。入力パラメーターが一致することを確認する必要があります。	references/video-operations.md

音声処理

操作	モード	説明	リファレンス
audio/convert	非同期	音声をトランスコードします。	references/audio-operations.md
audio/concat	非同期	音声ファイルを連結します。	references/audio-operations.md
audio/info	同期	音声のメタデータ（JSON）。	references/audio-operations.md

HLS ストリーミング

操作	モード	説明	リファレンス
hls/m3u8	同期	HLS プレイリストを返します（ファイルではありません。--output-mode url を使用してください）。	references/video-operations.md

ファイル操作

操作	モード	説明
upload	同期	ローカルファイル／URL を OSS にアップロードします。--uri と --target-key を併用してください。
download	同期	OSS オブジェクトをダウンロードします。--source と --output-path を併用してください。

処理モード

• 同期（x-oss-process）：画像の基本処理、video/snapshot、video/info、audio/info、hls/m3u8、AI 検出 — 結果はすぐに返されます
• 非同期（x-oss-async-process）：動画／音声のトランスコード、アニメーション、スプライト、スナップショット、結合、透かし抽出 — 自動検出され、完了まで自動でポーリングされます

---

使い方

python scripts/process.py \
  [--bucket BUCKET_NAME] \
  [--region REGION_ID] \
  (--source OSS_OBJECT_KEY | --uri URI) \
  --operations OPERATION [OPERATION ...] \
  [--output-mode url|download|save] \
  [--expires SECONDS] \
  [--output-path LOCAL_PATH] \
  [--target-key OSS_TARGET_KEY] \
  [--endpoint CUSTOM_ENDPOINT] \
  [--imm-project IMM_PROJECT_NAME] \
  [--dry-run]

--imm-project が使用されるのは blindwatermark-extract のみです。他の操作では、このフラグではなく IMM バケットバインディングを使用します。

--uri

アップロードせずに、ローカルファイルパスまたは URL（http/https）からファイルを処理します。スクリプトは一時キーに自動アップロードして処理し、後片付けを行います。--uri と --source は同時に指定できません。

--dry-run

生成された処理文字列と操作の詳細を JSON として標準出力に表示し、OSS に接続せずに終了します。

操作文字列の形式

各操作の形式は name:key=value,key=value です。パラメーターのない操作では、名前のみを使用します（例：info、video/info）。動画／音声の操作ではスラッシュ形式を使用します（video/convert、audio/convert）。

エンドツーエンドの例

ユーザーのリクエスト：

Resize `images/photo.jpg` in OSS to width 600px, add a bottom-right text watermark `Copyright 2026`, and download the result locally. The bucket is `my-media-bucket` in region `cn-shanghai`.

コマンド：

python scripts/process.py --bucket my-media-bucket --region cn-shanghai \
  --source images/photo.jpg \
  --operations "resize:w=600" "watermark:text=Copyright 2026,g=se,opacity=60,size=30" \
  --output-mode download \
  --output-path "$WORKSPACE_OUTPUT/photo-watermarked.jpg"

想定される結果の形式：

{
  "success": true,
  "mode": "download",
  "path": "/absolute/path/to/outputs/photo-watermarked.jpg",
  "size": 12345,
  "request_id": "xxxxxx"
}

解釈：

• success: true は、OSS の処理が正常に完了したことを意味します。
• path は、ユーザーに提示するローカルファイルのパスです。
• request_id は、トラブルシューティングに使用するサーバー側のリクエストトレース ID です。

その他の例

# HLS streaming (with IMM auto-setup)
python scripts/imm_admin.py auto-setup --bucket my-bucket --region cn-hangzhou
# → Capture project name from output
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --source videos/input.mp4 \
  --operations "hls/m3u8:ss=15000,t=1800000,vcodec=h264,fps=25,s=1280x720,vb=2000000,acodec=aac,ab=128000" \
  --output-mode url

# Upload a local file to OSS
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --uri /path/to/report.pdf --operations upload --target-key documents/report.pdf

# Download a file from OSS
python scripts/process.py --bucket my-bucket --region cn-hangzhou \
  --source documents/report.pdf --operations download --output-path $WORKSPACE_OUTPUT/report.pdf

エッジケース

• カンマを含む watermark の値は、引用符で囲む必要があります。例：preprocess="resize:w=200,text=demo,image/logo.png"。
• video/snapshots の出力先キーにファイル拡張子を含めてはいけません。output/frames/frame.jpg ではなく、output/frames/frame を使用してください。
• video/concat は、タスクを送信する前に必ず入力の互換性を確認します。追加のローカル ffprobe 出力検証は、結果も --output-path でダウンロードする場合にのみ実行されます。
• 非同期メディアのポーリングは、デフォルトで 600 秒です。--timeout-seconds <n> または ALIBABA_CLOUD_ASYNC_TIMEOUT_SECONDS で上書きできます。
• blindwatermark-extract は単独で実行する必要があります。blindwatermark-embed は基本的な画像操作の後に実行できますが、チェーン内の最後の操作でなければなりません。

---

エラーからの復旧

エラー	原因	復旧方法
AccessDenied または InvalidArgument が連続して 2 回発生する	設定または認可の問題が解決しておらず、むやみに再試行すると誤った診断につながるおそれがあります	すぐに停止してください。出力をシミュレートしたり、ログを捏造したり、process.py の再試行を続けたりしないでください。aliyun configure list を実行して有効な CLI プロファイルを確認し、python scripts/check_permissions.py または該当する RAM ポリシー設定で RAM 権限を確認してください。復旧中に依存関係、環境変数、CLI 設定を変更した場合は、次に process.py を実行する前に python scripts/load_env.py と aliyun configure list を再実行してください。
task_id: null	IMM プロジェクトがバケットにバインドされていないか、blindwatermark-extract に --imm-project / ALIBABA_CLOUD_IMM_PROJECT が指定されていません	まず python scripts/imm_admin.py auto-setup --bucket <b> --region <r> を実行してください。blindwatermark-extract の場合は、必要に応じて --imm-project <project> も指定してください
NoSuchKey	ソースファイルが OSS に存在しません	--source のパスを確認するか、先に --uri と upload 操作でアップロードしてください
AccessDenied / 403	必要な権限が RAM ポリシーにありません	診断のため、python scripts/check_permissions.py を実行してください
InvalidArgument	パラメーターの形式が誤っているか、サポートされていない組み合わせです	パラメーターの表記を確認し、references/ のドキュメントと照合してください
非同期処理のタイムアウト／ポーリングが上限を超過	ジョブが大きすぎるか、キューが滞留しています	task_id を控え、後でもう一度試すようユーザーに伝えてください。sleep のループは使用しないでください

---

Quick References

• Parameter details: references/image-basic-operations.md, references/image-imm-operations.md, references/video-operations.md, references/audio-operations.md
• RAM Permissions: references/ram-policies.md
• Format Support & Limitations: references/limitations.md
• IMM Administration: references/imm-admin.md