このガイドは、開発者が AI エージェントと Alibaba Cloud Video on Demand (VOD) を統合する際に役立ちます。本ガイドでは、クイックスタートガイドと、大規模言語モデル (LLM) 向けに設計された API ドキュメント構造を提供します。
実現できること
このドキュメントを使用することで、AI エージェントは次のことができるようになります。
VOD のコア機能の理解：構造化されたモジュールの概要を使用して、メディアアップロード、トランスコーディング、再生、メディアアセット管理など VOD のコア機能を学習できます。
API 呼び出しの学習：llms.txt インデックスを使用して、モジュール固有のドキュメントを検索できます。これらのドキュメントには、AI エージェントが VOD API を呼び出す方法を学習するための API 操作、パラメーターの説明、使用例が含まれています。
認証と認可の理解：AccessKey や STS 一時的な認証情報など、サポートされている認証方法を理解することで、VOD API 呼び出しの認証情報を設定する方法を学習できます。
一般的なエラーの処理：提供されている一般的なエラーコードとトラブルシューティング方法のリストを使用して、問題を自身で解決する方法を学習できます。
前提条件
VOD API を使用する前に、次の手順を完了してください。
VOD の有効化：Alibaba Cloud コンソールで VOD を有効化してください。
AccessKey の作成：RAM コンソールで AccessKey ID と AccessKey Secret を作成してください。セキュリティ上の理由から、VOD API 呼び出し専用の RAM ユーザーを作成し、
AliyunVODFullAccess権限を付与することを推奨します。SDK のインストール：VOD API の呼び出しには、Alibaba Cloud SDK を使用します。VOD の POP 製品コードは
vodで、API バージョンは2017-03-21です。
デフォルトのパラメーターと規約
VOD API を呼び出す前に、次のデフォルト値と規約を理解する必要があります。
デフォルトのアプリケーション ID：
app-1000000。マルチアプリケーションシステムが有効になっていない場合、すべての API 呼び出しはデフォルトのアプリケーションに関連付けられます。デフォルトのストレージ：
StorageLocationを指定しない場合、ファイルはデフォルトのストレージアドレスにアップロードされます。デフォルトのトランスコーディングテンプレートグループ：
TemplateGroupIdを指定せず、ワークフローが関連付けられていない場合、デフォルトのトランスコーディングテンプレート (トランスコーディングなしのテンプレートグループ) が使用されます。API 呼び出しプロトコル：安全なデータ転送を確保するために、すべての API 呼び出しに HTTPS を使用します。
リクエスト署名：すべての API リクエストには署名検証が必要です。署名方式には
HMAC-SHA1が使用されます。SDK は署名を自動的に処理します。
llms.txt
llms.txt ファイルは、LLM に最適化され、Alibaba Cloud OSS でホストされている VOD ドキュメントのインデックスです。このファイルは、公式ドキュメントをシナリオ、API、サブドキュメントパス別に再編成し、コード生成をガイドするための 「Common mistakes to avoid」 リストを抽出します。これにより、コーディングエージェントはファイルを一度にロードし、必要に応じてセクションを展開できます。
インデックスファイルにアクセスするためのベース URL は次のとおりです。
https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/llms.txt公式ドキュメントとの関係：llms.txt は インデックス です。Media Upload/Upload from URL.md などのサブドキュメントは、公式ドキュメントの主要な情報を要約したものです。VOD ドキュメントチームが、公式サイトと一貫性が保たれるように内容を同期しています。
VOD モジュール
VOD の機能はモジュールに整理されており、各モジュールは一連の API 操作に対応しています。次の表にこれらのモジュールと、そのドキュメントへのリンクを示します。これらは llms.txt にもインデックスされています。これらのリンクは、AI エージェントが直接利用するためのものです。
モジュール | 説明 | llms ドキュメントリンク |
メディアアップロード | コンソール、クライアントサイド SDK、サーバーサイド API、または URL を使用して、オーディオ、ビデオ、画像、および補助メディアアセットをアップロードします。 | |
メディアアセット管理 | アップロードされたメディアアセットを管理します。情報の照会、メタデータの更新、アセットの削除、ステータスの設定などの操作を実行します。 | |
メディア処理 | トランスコーディング、スナップショットキャプチャ、アニメーション画像生成、ウォーターマーク合成などの機能を使用して、オーディオおよびビデオファイルを処理します。カスタムトランスコーディングテンプレートグループ、ワークフローオーケストレーション、およびスマートレビューとスマートカバー生成用の AI テンプレートをサポートしています。 | |
オーディオとビデオの再生 | アップロードおよび処理されたオーディオおよびビデオコンテンツを再生します。再生は、コンソール、Player SDK、またはサードパーティのプレーヤーで利用できます。 | |
メディアセキュリティ | アクセス制限、URL 認証、ビデオ暗号化、電子透かしなどのメカニズムを通じて、オーディオおよびビデオコンテンツのホットリンク、不正ダウンロード、および違法な配信を防止するセキュリティフレームワークです。 | |
メディアレビュー | スマートレビューと手動レビュー機能を提供します。スマートレビューは、オーディオおよびビデオ内の非準拠コンテンツ (ポルノ、暴力的、政治的なコンテンツなど) を自動的に識別し、カスタム AI レビューテンプレートをサポートします。手動レビューは、レビュータスクを作成し、結果を送信するための API を提供します。 | |
ビデオ AI | スマートレビュー、タグ認識、DNA 比較、カバー生成など、オーディオおよびビデオコンテンツの自動分析と処理を実行します。 | |
クラウド編集 | クラウド編集機能を提供します。API を使用して、編集プロジェクトの作成、素材の管理、ビデオ合成を実行できます。 | |
CDN 配信と高速化 | 高速化ドメイン名を設定し、再生 URL と再生認証情報を取得して、オーディオとビデオを配信および再生します。CDN 高速化、URL 認証、DRM 暗号化などの安全な再生機能をサポートしています。 | |
イベント通知 | アップロードやトランスコーディングの完了などのメディア処理イベントに関する通知を、HTTP コールバックまたは Message Service (MNS) を介して受信します。 | |
データ統計 | 使用状況の照会、リソース消費の監視、および統計分析を実行して、サービスの使用状況とリソースの利用率を理解します。 | |
マルチアプリケーションシステム | 単一の Alibaba Cloud アカウントで複数のアプリケーションを作成し、メディアアセット、設定、権限を論理的に分離します。これにより、メディアアップロード、再生、メディアアセット管理、およびメッセージコールバックに対するアプリケーションレベルの制御がサポートされます。 | |
サーバーサイド SDK | Java、Python、PHP、および C/C++ 用の SDK を使用して、メディアのアップロード、管理、および処理のための API を呼び出します。 | |
ライブの VOD 化 | ライブストリームをリアルタイムで録画し、オンデマンドのメディアアセットとして自動的に保存して、その後の再生、管理、および配信に利用できます。 | |
課金 | ストレージ容量、トラフィックと帯域幅、トランスコーディング時間、メディア管理、付加価値サービスなどのメトリクスに基づいて、従量課金制およびサブスクリプション課金を提供します。 | |
ミニシリーズソリューション | VOD に基づくミニシリーズの制作と運用のためのワンストップソリューションです。コンテンツ制作、メディアアセット管理、データインサイト、効率的な配信と再生を提供します。 | |
Player SDK | Alibaba Cloud が開発した、Web、Android、iOS 向けのフルプラットフォームのオーディオおよびビデオ再生ツールで、安定したスムーズなオンデマンドおよびライブストリーミング再生を提供します。 | |
AliPlayerKit | ビデオサービス向けのローコードのプレーヤー UI フレームワークで、拡張可能なコンポーネントとシナリオベースのソリューションを提供し、オンデマンド、ライブストリーミング、その他のシナリオとの迅速な統合を可能にします。 | |
API リファレンス | メディアアセットのライフサイクル全体にわたる OpenAPI を提供し、アップロード、管理、処理、配信、再生などの操作をサポートします。 |
メディアアップロード
VOD は、メディアをアップロードするためのいくつかの方法を提供します。
サーバーサイドアップロード：
CreateUploadVideoAPI を呼び出してアップロード URL と認証情報を取得し、SDK または HTTP 経由でファイルをアップロードします。この方法は、バックエンドサーバーからのアップロードに最適です。クライアントサイドアップロード：AccessKey または STS 一時的な認証情報を使用して、クライアントから直接ビデオをアップロードします。
URL からのアップロード：
UploadMediaByURLAPI を呼び出し、ソースファイルの URL を指定します。VOD サービスは自動的にファイルを取得してアップロードします。この方法は、一括移行やサードパーティ URL からのメディアのインポートに最適です。
主要なパラメーター
CreateUploadVideo を呼び出す際には、次のパラメーターが重要です。
パラメーター | タイプ | 必須 | デフォルト | 説明 |
FileName | String | はい | — | ソースメディアファイルのフルパスとファイル名 (拡張子を含む)。例： |
Title | String | はい | — | メディアのタイトル。最大 128 文字です。 |
Description | String | いいえ | — | オーディオまたはビデオの説明。最大長は 1,024 文字です。 |
CateId | Long | いいえ | — | カテゴリ ID。この ID は、コンソールで [設定管理] > [メディアアセット管理設定] > [カテゴリ管理] の順に選択して確認できます。 |
Tags | String | いいえ | — | 最大 16 個のタグをコンマ区切りで指定します。各タグは最大 32 文字です。 |
TemplateGroupId | String | いいえ | — | トランスコーディングテンプレートグループ ID。このパラメーターを指定すると、アップロード完了後にトランスコーディングが自動的にトリガーされます。この ID は、コンソールで [設定管理] > [メディア処理] > [トランスコーディングテンプレートグループ] の順に選択して確認できます。 |
WorkflowId | String | いいえ | — | ワークフロー ID。このパラメーターを指定すると、アップロード完了後にワークフローが自動的にトリガーされます。 |
StorageLocation | String | いいえ | — | ストレージアドレス。指定しない場合、ファイルはデフォルトのストレージアドレスにアップロードされます。このアドレスは、コンソールで [設定管理] > [メディアアセット管理設定] > [ストレージ] の順に選択して確認できます。 |
CoverURL | String | いいえ | — | カスタムビデオカバーの URL。 |
AppId | String | いいえ |
| アプリケーション ID。マルチアプリケーションシステムでアプリケーションを指定します。 |
メディアアセット管理
メディアアセット管理モジュールは、アップロードされたオーディオ、ビデオ、および補助メディアアセットを管理するためのモジュールです。コア操作には次のものがあります。
メディアアセット情報の照会：
GetVideoInfo(単一のビデオを照会)、GetVideoInfos(複数のビデオを一括で照会)、SearchMedia(メディアアセットを検索)メディアアセット情報の更新：
UpdateVideoInfo(ビデオ情報を更新)、UpdateImageInfos(画像情報を更新)メディアアセットの削除：
DeleteVideo(ビデオを削除)、DeleteAttachedMedia(補助メディアアセットを削除)一括操作：
BatchGetMediaInfos(一度に最大 20 個のメディアアセットの情報を取得)
メディア ID (VideoId、MediaId、または ImageId) は、メディアアセットを管理するための一意の識別子です。ビデオをアップロードすると、CreateUploadVideo は VideoId を返します。補助メディアアセットをアップロードすると、CreateUploadAttachedMedia は MediaId を返します。
メディア処理
メディア処理モジュールは、オーディオおよびビデオのトランスコーディング、スナップショットキャプチャ、AI レビューなどの機能を提供します。
トランスコーディング：トランスコーディングテンプレートグループ (
AddTranscodeTemplateGroup) を使用してトランスコーディングパラメーターを設定します。アップロード時にTemplateGroupIdを指定するか、ワークフローを使用することで、自動トランスコーディングをトリガーできます。ビデオコーデック (例： H.264)、解像度 (例： 640×360)、ビットレート (例： 400 kbps) などのパラメーターを設定できます。スナップショットキャプチャ：スナップショットテンプレート (
AddVodTemplateでTemplateTypeをSnapshotに設定) を使用してスナップショットパラメーターを設定します。標準のスナップショットやスプライトなど、さまざまなタイプをサポートしています。スマートレビュー：AI テンプレート (
AddAITemplateでTemplateTypeをAIMediaAuditに設定) を使用して、レビュー項目 (ポルノ、暴力的、政治的なコンテンツなど) と範囲 (カバー画像、ビデオコンテンツ、タイトルテキスト) を設定します。ビデオのアップロード後に自動的にレビューが開始されます。CreateAuditを呼び出して手動でレビューすることもできます。スマートカバー：AI テンプレート (
TemplateTypeをAIImageに設定) を使用して、ビデオカバーを自動的に生成します。
スマートレビューのパラメーター
AddAITemplate を呼び出して AI レビューテンプレートを作成する場合：
パラメーター | タイプ | 必須 | デフォルト | 説明 |
TemplateName | String | はい | — | AI テンプレートの名前。最大長は 128 バイトです。 |
TemplateType | String | はい | — | テンプレートタイプ： |
TemplateConfig | String | はい | — | JSON 文字列としてのテンプレート設定。 |
配信と再生
配信と再生モジュールは、ビデオ再生 URL の取得と安全な再生機能を提供します。
再生 URL の取得：
GetPlayInfoを呼び出してビデオ再生 URL を取得します。出力形式 (MP4、FLV、HLS など) と解像度を指定できます。再生認証情報の取得：
GetVideoPlayAuthを呼び出して、暗号化再生 (HLS 標準暗号化または Alibaba Cloud の独自暗号化) のための再生認証情報を取得します。ドメイン名管理：
AddVodDomainを呼び出して高速化ドメイン名を追加し、BatchStartVodDomainで有効化し、BatchStopVodDomainで無効化します。
ドメイン設定パラメーター
AddVodDomain を呼び出して高速化ドメイン名を追加する場合：
パラメーター | タイプ | 必須 | デフォルト | 説明 |
DomainName | String | はい | — | 高速化ドメイン名。ワイルドカードドメイン名もサポートされています。例： |
Sources | String | はい | — | オリジンアドレスのリストを JSON 配列として指定します。形式： |
Scope | String | いいえ |
| 高速化の範囲： |
一般的なエラーとトラブルシューティング
エラーコード | 説明 | トラブルシューティング |
InvalidAccessKeyId.NotFound | 指定された AccessKey ID は存在しません。 |
|
SignatureDoesNotMatch | 署名が計算結果と一致しません。 | SDK のデバッグログを有効にして、署名の問題をトラブルシューティングします： |
InvalidParameter | パラメーターが無効です。 | 各 API のドキュメントを参照して、リクエストパラメーターが要件 (タイプ、長さ、必須かどうかなど) を満たしているか確認してください。 |
Forbidden.AccessDenied | 権限が不十分です。 | RAM ユーザーに必要な VOD 権限 ( |
ServiceUnavailable | サービスは一時的に利用できません。 | これは一時的なサービスの問題を示します。エクスポネンシャルバックオフを使用してリクエストを再試行してください。 |
QuotaExceeded.UploadVideo | アップロードされたビデオの数がクォータを超えました。 | アカウントのアップロードクォータを確認してください。チケットを送信してクォータの引き上げをリクエストできます。 |
MediaNotFound | メディアアセットが存在しません。 |
|
InvalidStatus.Media | メディアアセットがこの操作に対して無効な状態です。 | アセットがこの操作を妨げる状態 (例： 「レビュー中」) にあります。再試行する前に |