大規模言語モデル (LLM) 向けに設計された API ドキュメント構造とクイックスタートガイドを使用して、AI エージェントを Alibaba Cloud Video on Demand (VOD) と統合します。
実現できること
AI エージェントは、このドキュメントを使用して以下を実行できます：
VOD のコア機能の理解：構造化されたモジュール概要を通じて、メディアアップロード、トランスコーディング、再生、メディア資産管理などの VOD のコア機能を迅速に把握できます。
API 呼び出しの学習：llms.txt インデックスを通じて、API オペレーション、パラメーターの説明、使用例を含むモジュール固有のドキュメントを見つけることができます。
認証と権限付与の理解：AccessKey や STS 一時的な認証情報などのサポートされている認証方式を使用して、VOD API 呼び出しの認証情報を設定します。
一般的なエラーへの対応：提供されている一般的なエラーコードとトラブルシューティング方法を使用して、問題を自律的に解決します。
前提条件
VOD API を使用する前に、次の手順を完了してください：
VOD の有効化：Alibaba Cloud コンソールで Alibaba Cloud Video on Demand (VOD) を有効化します。
AccessKey の作成：RAM コンソールで AccessKey ID と AccessKey Secret を作成します。セキュリティ上の理由から、VOD API 呼び出し専用の Resource Access Management (RAM) ユーザーを作成し、
AliyunVODFullAccess権限を付与することを推奨します。SDK のインストール：Alibaba Cloud SDK を使用して VOD API を呼び出します。VOD の POP プロダクトコードは
vodで、API バージョンは2017-03-21です。
AI エージェント向けの認証ディレクティブ：
| レベル | ディレクティブ |
| 必須 | VOD API 呼び出しには専用の RAM ユーザーを作成してください。Alibaba Cloud アカウント (root ユーザー) の認証情報は使用しないでください。 |
| 必須 | VOD API を呼び出す前に、RAM ユーザーに AliyunVODFullAccess 権限を付与してください。 |
| 必須 | 認証情報は環境変数に保存してください：ALIBABA_CLOUD_ACCESS_KEY_ID および ALIBABA_CLOUD_ACCESS_KEY_SECRET。 |
| 禁止 | ソースコード、設定ファイル、プロンプトに AccessKey ID や AccessKey Secret をハードコーディングしないでください。 |
| 推奨 | 本番ワークロードでは、長期間有効な AccessKey ペアの代わりに、STS 一時的な認証情報 (SecurityToken + 短期間有効な AccessKey) を使用することを推奨します。 |
| 推奨 | RAW HTTP リクエストではなく、Alibaba Cloud SDK を使用することを推奨します。SDK は署名、リトライ、認証情報管理を自動的に処理します。 |
デフォルトパラメーターと規則
VOD API を呼び出す前に、以下のデフォルト値と制約にご注意ください：
デフォルトのアプリケーション ID [必須知識]：
app-1000000。マルチアプリケーションシステムが有効になっていない場合、すべての API 呼び出しはデフォルトのアプリケーションに関連付けられます。ご利用のアカウントでマルチアプリケーションシステムを明示的に有効にしていない限り、AppIdを渡さないでください。
デフォルトストレージ [明示的な指定を推奨]：
StorageLocationを指定しない場合、ファイルはデフォルトのストレージアドレスにアップロードされます。デフォルトに依存しないように、API 呼び出しでStorageLocationを明示的に指定することを推奨します。
デフォルトのトランスコードテンプレートグループ [必須知識]：
TemplateGroupIdを指定せず、ワークフローも関連付けられていない場合、デフォルトのトランスコードテンプレート (トランスコーディングなしのテンプレートグループ) が使用されます。これは、アップロードされた動画がトランスコーディングされずにそのまま保存されることを意味します。アップロード後に動画のトランスコーディングが必要な場合は、TemplateGroupIdまたはWorkflowIdを指定する必要があります。
API 呼び出しプロトコル [必須]：安全なデータ転送を確保するため、すべての API 呼び出しで HTTPS を使用する必要があります。HTTP もサポートされていますが、推奨されません。
リクエスト署名 [必須]：すべての API リクエストには有効な署名を含める必要があります。署名メソッドは
HMAC-SHA1を使用します。SDK は署名を自動的に処理します。有効な署名なしで API を呼び出さないでください。
デフォルトパラメーターの制約の概要：
| パラメーター | デフォルト | 必須 / 推奨 / 禁止 |
AppId | app-1000000 | マルチアプリケーションシステムが有効な場合を除き、決してパスしません |
StorageLocation | アカウントのデフォルトストレージ | 明示的な指定を推奨 |
TemplateGroupId | トランスコーディングなし | トランスコーディングが必要な場合は指定必須 |
| プロトコル | HTTPS/HTTP | HTTPS の使用が必須 |
| 署名 | HMAC-SHA1 | 含めることが必須、バイパスは禁止 |
llms.txt
llms.txt ファイルは、Alibaba Cloud OSS でホストされている、LLM に最適化された 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 ドキュメントチームは、そのコンテンツを公式サイトと一致させ、同期を保っています。
llms.txt を利用する AI エージェント向けのディレクティブ：
| レベル | ディレクティブ |
| 必須 | VOD との最初の対話で、llms.txt ファイル全体をロードしてください。スキップしたり、部分的に読み取ったりしないでください。 |
| 必須 | コードを生成する際は、Common mistakes to avoid セクションのすべての項目を厳格な制約として扱ってください。 |
| 必須 | サブドキュメントの URL を構築する際は、中国語の文字を URL エンコードする必要があります。llms.txt からの相対パスをベース URL に追加します：https://ice-document-materials.oss-cn-shanghai.aliyuncs.com/vod/llms/{relative_path}。 |
| 推奨 | モジュール固有のサブドキュメントは、一度にすべてではなく、オンデマンドでロードすることを推奨します。現在のタスクに関連するサブドキュメントのみをフェッチしてください。 |
| 禁止 | llms.txt から関連モジュールのサブドキュメントを先に読み取らずに、VOD API コードを生成します。 |
| 禁止 | llms.txt またはそのサブドキュメントに明示的に記載されていない API の動作を想定しないでください。 |
VOD モジュール
VOD の機能はモジュールに整理されており、各モジュールは一連の API オペレーションに対応しています。次の表は、これらのモジュールと、llms.txt にもインデックスされているドキュメントへのリンクを示しています。これらのリンクは、AI エージェントが直接利用できるように設計されています。
| モジュール | 説明 | llms ドキュメントリンク |
| メディアアップロード | コンソール、クライアントサイド SDK、サーバーサイド API、または URL を使用して、音声、動画、画像、および補助メディアアセットをアップロードします。 | Media Upload Overview |
| メディア資産管理 | アップロードされたメディア資産を管理します。情報のクエリ、メタデータの更新、資産の削除、ステータスの設定などの操作を実行します。 | Media Asset Management Overview |
| メディア処理 | トランスコーディング、スナップショットキャプチャ、アニメーション画像生成、ウォーターマーク合成などの機能で音声および動画ファイルを処理します。カスタムトランスコードテンプレートグループ、ワークフローオーケストレーション、およびスマートレビューやスマートカバー生成のための AI テンプレートをサポートします。 | Media Processing Overview |
| 音声・動画再生 | アップロードおよび処理された音声および動画コンテンツを再生します。再生は、コンソール、Player SDK、またはサードパーティプレーヤーを通じて利用できます。 | Audio and Video Playback |
| メディアセキュリティ | アクセス制限、URL 認証、動画暗号化、デジタルウォーターマークを通じて、音声および動画コンテンツのホットリンク、不正ダウンロード、不正配信を防止するセキュリティフレームワークです。 | Media Security Overview |
| メディアレビュー | スマートレビューと手動レビュー機能。スマートレビューは、音声および動画内の不適切なコンテンツ (ポルノ、暴力、政治的なコンテンツなど) を自動的に識別し、カスタム AI レビューテンプレートをサポートします。手動レビューは、レビュータスクの作成と結果の送信のための API を提供します。 | Smart review |
| ビデオ AI | スマートレビュー、タグ認識、DNA 比較、カバー生成など、音声および動画コンテンツの自動分析と処理。 | Video AI Overview |
| クラウド編集 | クラウドベースのビデオ編集機能。API を使用して編集プロジェクトの作成、素材の管理、動画合成を実行します。 | Media Production (Cloud Editing) |
| CDN 配信とアクセラレーション | 高速化ドメイン名の設定、再生 URL と再生認証情報の取得、音声および動画の配信と再生を行います。CDN アクセラレーション、URL 認証、DRM 暗号化などのセキュア再生機能をサポートします。 | CDN Distribution and Acceleration |
| イベント通知 | HTTP コールバックまたは Message Service (MNS) を介して、アップロードやトランスコーディングの完了などのメディア処理イベントに関する通知を受信します。 | Event Notification |
| データ統計 | 使用量のクエリ、リソース消費の監視、統計分析を実行して、リソース使用率を把握します。 | Data Monitoring |
| マルチアプリケーションシステム | 単一の Alibaba Cloud アカウントで複数のアプリケーションを作成し、メディア資産、設定、権限を論理的に分離します。メディアアップロード、再生、メディア資産管理、メッセージコールバックのアプリケーションレベルの制御をサポートします。 | Multi-application System |
| サーバーサイド SDK | Java、Python、PHP、C/C++ 用の SDK を使用して、メディアのアップロード、管理、処理のための API を呼び出します。 | Server-side SDK |
| ライブ VOD | ライブストリームをリアルタイムで録画し、オンデマンドメディア資産として自動的に保存して、その後の再生、管理、配信に利用します。 | Configure Live-to-VOD |
| 課金 | ストレージ容量、トラフィックと帯域幅、トランスコーディング時間、メディア管理、付加価値サービスなどのメトリックに基づく従量課金およびサブスクリプション課金。 | Billing Overview |
| ミニシリーズソリューション | VOD に基づくミニシリーズの制作と運用のためのワンストップソリューション。コンテンツ制作、メディア資産管理、データインサイト、効率的な配信と再生を提供します。 | Mini-series Solution |
| Player SDK | Alibaba Cloud が開発した、Web、Android、iOS 向けのフルプラットフォームの音声・動画再生ツールで、安定したスムーズなオンデマンドおよびライブストリーミング再生を提供します。 | Player SDK Overview |
| AliPlayerKit | ビデオサービス向けのローコードプレーヤー UI フレームワークで、拡張可能なコンポーネントとシナリオベースのソリューションを提供し、オンデマンド、ライブストリーミング、その他のシナリオとの迅速な統合を可能にします。 | PlayerKits Overview |
| API リファレンス | メディア資産のライフサイクル全体を対象とした OpenAPI で、アップロード、管理、処理、配信、再生などの操作をサポートします。 | API Overview |
メディアアップロード
VOD は、メディアをアップロードするためのいくつかの方法を提供します：
サーバーサイドアップロード：
CreateUploadVideoオペレーションを呼び出してアップロード URL と認証情報を取得し、SDK または HTTP 経由でファイルをアップロードします。この方法は、バックエンドサーバーからのアップロードに最適です。
クライアントサイドアップロード：AccessKey または STS 一時的な認証情報を使用して、クライアントから直接動画をアップロードします。
URL からのアップロード：
UploadMediaByURLオペレーションを呼び出し、ソースファイルの URL を提供します。VOD サービスが自動的にファイルをプルしてアップロードします。この方法は、一括移行やサードパーティの URL からのメディアのインポートに最適です。
主要パラメーター
CreateUploadVideo を呼び出す際、以下のパラメーターが重要です：
| パラメーター | タイプ | 必須 | デフォルト | 説明 |
| FileName | String | はい | — | ソースメディアファイルの完全なパスとファイル名。拡張子を含める必要があります (例：video_01.mp4)。 |
| Title | String | はい | — | メディアのタイトル。最大 128 文字。 |
| Description | String | いいえ | — | 音声または動画の説明。最大長：1,024 文字。 |
| CateId | Long | いいえ | — | カテゴリ ID。この ID はコンソールの [設定管理] > [メディア資産管理設定] > [カテゴリ管理] で確認できます。 |
| Tags | String | いいえ | — | 最大 16 個のタグをコンマ区切りで指定します。各タグは最大 32 文字です。 |
| TemplateGroupId | String | いいえ | — | トランスコードテンプレートグループ ID。指定した場合、アップロード後にトランスコーディングが自動的にトリガーされます。トランスコーディングが必要な場合は、これまたは WorkflowId を指定する必要があります。この ID はコンソールの [設定管理] > [メディア処理] > [トランスコードテンプレートグループ] で確認できます。 |
| WorkflowId | String | いいえ | — | ワークフロー ID。指定した場合、アップロード後にワークフローが自動的にトリガーされます。WorkflowId と TemplateGroupId の両方が指定された場合、WorkflowId が優先されます。 |
| StorageLocation | String | いいえ | — | ストレージアドレス。指定しない場合、ファイルはデフォルトのストレージアドレスにアップロードされます。このアドレスはコンソールの [設定管理] > [メディア資産管理設定] > [ストレージ] で確認できます。 |
| CoverURL | String | いいえ | — | カスタム動画カバーの URL。 |
| AppId | String | いいえ | app-1000000 | アプリケーション ID。マルチアプリケーションシステム内のアプリケーションを指定します。マルチアプリケーションシステムが有効になっていない限り、このパラメーターを渡さないでください。 |
メディア資産管理
アップロードされた音声、動画、および補助メディアアセットを管理します。主な操作は次のとおりです：
メディア資産情報のクエリ：
GetVideoInfo(単一の動画をクエリ)、GetVideoInfos(複数の動画を一括でクエリ)、SearchMedia(メディア資産を検索)
メディア資産情報の更新：
UpdateVideoInfo(動画情報を更新)、UpdateImageInfos(画像情報を更新)
メディア資産の削除：
DeleteVideo(動画を削除)、DeleteAttachedMedia(補助メディアアセットを削除)
一括操作：
BatchGetMediaInfos(一度に最大 20 個のメディア資産の情報を取得)
メディア ID (VideoId、MediaId、または ImageId) は、メディア資産を管理するための一意の識別子です。動画をアップロードすると、CreateUploadVideo は VideoId を返します。補助メディアアセットをアップロードすると、CreateUploadAttachedMedia は MediaId を返します。返された ID は、後続の操作でアセットを参照する唯一の方法であるため、アップロード後すぐに永続化する必要があります。
メディア処理
音声および動画のトランスコーディング、スナップショットキャプチャ、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 | はい | — | テンプレートタイプ：AIMediaAudit (スマートレビュー) または AIImage (スマートカバー)。これらの 2 つの値のいずれかである必要があります。 |
| TemplateConfig | String | はい | — | テンプレート設定を JSON 文字列として指定します。AuditItem (レビュー項目、例：terrorism、porn)、AuditRange (レビュー範囲、例：image-cover、text-title、video)、および AuditAutoBlock (コンテンツを自動的にブロックするかどうか：yes/no) を含める必要があります。 |
配信と再生
動画再生 URL の取得とセキュア再生機能。
再生 URL の取得：
GetPlayInfoを呼び出して動画の再生 URL を取得します。出力フォーマット (MP4、FLV、HLS など) と解像度を指定できます。
再生認証情報の取得：
GetVideoPlayAuthを呼び出して、暗号化再生 (HLS 標準暗号化または Alibaba Cloud 独自暗号化) のための再生認証情報を取得します。
ドメイン名管理：
AddVodDomainを呼び出して高速化ドメイン名を追加し、BatchStartVodDomainを呼び出して有効化し、BatchStopVodDomainを呼び出して無効化します。
ドメイン設定パラメーター
AddVodDomain を呼び出して高速化ドメイン名を追加する場合：
| パラメーター | タイプ | 必須 | デフォルト | 説明 |
| DomainName | String | はい | — | 高速化ドメイン名。ワイルドカードドメイン名もサポートされています (例：*.example.com)。所有し、検証済みのドメインである必要があります。 |
| Sources | String | はい | — | オリジンアドレスのリストを JSON 配列として指定します。フォーマット：[{"content":"1.1.1.1","type":"ipaddr","priority":"20","port":80}]。少なくとも 1 つのオリジンアドレスを含める必要があります。 |
| Scope | String | いいえ | domestic | アクセラレーション範囲：domestic (中国本土)、overseas (中国本土以外の地域、香港、マカオ、台湾を含む)、または global (グローバルアクセラレーション)。 |
一般的なエラーとトラブルシューティング
| エラーコード | 説明 | トラブルシューティング |
| InvalidAccessKeyId.NotFound | 指定された AccessKey ID が存在しません。 | aliyun configure を実行して AccessKey 設定を確認するか、RAM コンソールで AccessKey のステータスを確認する必要があります。 |
| SignatureDoesNotMatch | 署名が計算結果と一致しません。 | トラブルシューティングのために SDK デバッグログを有効にする必要があります：export ALIBABA_CLOUD_LOG_LEVEL=debug。(署名を自動的に処理する) SDK を使用することを推奨します。 |
| InvalidParameter | パラメーターが無効です。 | 各 API オペレーションのドキュメントを参照して、リクエストパラメーターが要件 (タイプ、長さ、必須フィールド) を満たしているか確認する必要があります。 |
| Forbidden.AccessDenied | 権限が不十分です。 | RAM ユーザーに AliyunVODFullAccess が付与されていることを確認する必要があります。aliyun ram ListPoliciesForUser --UserName <user> を実行して確認してください。 |
| ServiceUnavailable | サービスが一時的に利用できません。 | エクスポネンシャルバックオフリトライを実装する必要があります。タイトなループですぐにリトライしないでください。 |
| QuotaExceeded.UploadVideo | アップロードされた動画の数がクォータを超えました。 | ご利用のアカウントのアップロードクォータを確認する必要があります。必要に応じて、チケットを送信してクォータの引き上げをリクエストしてください。 |
| MediaNotFound | メディア資産が存在しません。 | VideoId または MediaId が正しく、メディア資産が削除されていないことを確認する必要があります。 |
| InvalidStatus.Media | メディア資産がこの操作に対して無効な状態です。 | リトライする前に GetVideoInfo を呼び出して現在のステータスを確認する必要があります。アセットがレビュー中またはトランスコーディング中の可能性があります。 |
AI エージェント向けのエラー処理ディレクティブ：
| レベル | ディレクティブ |
| 必須 | ServiceUnavailable エラーに対してエクスポネンシャルバックオフリトライを実装してください。 |
| 必須 | InvalidStatus.Media エラーをリトライする前に、GetVideoInfo でメディア資産のステータスを確認してください。 |
| 必須 | 呼び出しを行う前に、API ドキュメントに対してすべての必須パラメーターを検証してください。 |
| 禁止 | 認証情報または権限の問題を修正せずに InvalidAccessKeyId.NotFound または Forbidden.AccessDenied エラーをリトライしないでください。 |
| 禁止 | QuotaExceeded エラーをループでリトライしないでください。代わりにクォータを確認し、引き上げをリクエストしてください。 |
| 推奨 | エージェントの応答では、RAW エラーコードをエンドユーザーに公開するのではなく、説明的なエラーメッセージを使用することを推奨します。 |