すべてのプロダクト
Search

このプロダクト

    ApsaraVideo VOD:RegisterMedia

    ドキュメントセンター

    ApsaraVideo VOD:RegisterMedia

    最終更新日:Jun 15, 2026

    OSSバケットのメディアファイルをApsaraVideo VODに登録します。トランスコーディングやスナップショットなどの機能をメディアに適用するには、まずファイルを登録して必要なメタデータを生成する必要があります。

    操作説明

    • ApsaraVideo VODを使用してOSSバケットの音声および動画ファイルを処理するには、まずファイルを登録する必要があります。登録後、メディアIDを使用してトランスコーディング、スナップショット、AI 処理などのタスクを開始できます。

    • 1 回のAPI 呼び出しで最大 10 件のOSSメディアファイルを登録できます。リクエスト内のすべてのファイルは同じストレージロケーションを共有する必要があります。

    • ApsaraVideo VODに直接アップロードされたメディアファイルは、他のテンプレートグループが指定されていない場合、デフォルトのテンプレートグループを使用して自動的にトランスコーディングされます。ただし、登録されたメディアは自動的にトランスコーディングされません。トランスコーディングをトリガーするには、登録時にトランスコーディングテンプレートグループIDを指定する必要があります。

    • ファイルを再登録すると、既存のメディアIDが返され、その他の操作は行われません。

    • 登録するメディアファイルに有効なファイル拡張子があることを確認してください。有効でない場合、登録は失敗します。

    今すぐお試しください

    この API を OpenAPI Explorer でお試しください。手作業による署名は必要ありません。呼び出しに成功すると、入力したパラメーターに基づき、資格情報が組み込まれた SDK コードが自動的に生成されます。このコードをダウンロードしてローカルで使用できます。

    テスト

    RAM 認証

    下表に、この API を呼び出すために必要な認証情報を示します。認証情報は、RAM (Resource Access Management) ポリシーを使用して定義できます。以下で各列名について説明します。

    • アクション：特定のリソースに対して実行可能な操作。ポリシー構文ではAction要素として指定します。

    • API：アクションを具体的に実行するための API。

    • アクセスレベル：各 API に対して事前定義されているアクセスの種類。有効な値：create、list、get、update、delete。

    • リソースタイプ：アクションが作用するリソースの種類。リソースレベルでの権限をサポートするかどうかを示すことができます。ポリシーの有効性を確保するため、アクションの対象として適切なリソースを指定してください。

      • リソースレベルの権限を持つ API の場合、必要なリソースタイプはアスタリスク (*) でマークされます。ポリシーのResource要素で対応する ARN を指定してください。

      • リソースレベルの権限を持たない API の場合、「すべてのリソース」と表示され、ポリシーのResource要素でアスタリスク (*) でマークされます。

    • 条件キー：サービスによって定義された条件のキー。このキーにより、きめ細やかなアクセス制御が可能になります。この制御は、アクション単体に適用することも、特定のリソースに対するアクションに適用することもできます。Alibaba Cloud は、サービス固有の条件キーに加えて、すべての RAM 統合サービスに適用可能な一連の共通条件キーを提供しています。

    • 依存アクション：ある特定のアクションを実行するために、前提として実行が必要となる他のアクション。依存アクションの権限も RAM ユーザーまたは RAM ロールに付与する必要があります。

    アクション

    アクセスレベル

    リソースタイプ

    条件キー

    依存アクション

    vod:RegisterMedia

    create

    *All Resource

    *

    		 なし なし

    リクエストパラメーター

    パラメーター

    型

    必須 / 任意

    説明

    例
    RegisterMetadatas

    string

    必須

    登録するメディアのメタデータ。このパラメーターはJSON 文字列です。最大 10 件のメディアファイルのメタデータを指定できます。パラメーター構造の詳細については、下記のRegisterMetadataテーブルを参照してください。

    [{"FileURL":"https://****.oss-cn-shanghai.aliyuncs.com/video/test/video123.m3u8","Title":"VideoName"}]
    TemplateGroupId

    string

    任意

    トランスコーディングテンプレートグループのID。以下のいずれかの方法でIDを取得できます。

    • ApsaraVideo VODコンソールにログインします。左側のナビゲーションペインで、設定管理 > メディア処理設定 > トランスコーディングテンプレートグループを選択して、トランスコーディングテンプレートグループIDを確認します。

    • AddTranscodeTemplateGroup 操作を呼び出して、トランスコーディングテンプレートグループを作成します。レスポンスのTranscodeTemplateGroupIdの値がトランスコーディングテンプレートグループのIDです。

    • ListTranscodeTemplateGroup 操作を呼び出して、トランスコーディングテンプレートグループを照会します。レスポンスのTranscodeTemplateGroupIdの値がトランスコーディングテンプレートグループのIDです。

    説明

    • メディアのトランスコーディングが不要な場合は、このパラメーターをVOD_NO_TRANSCODEに設定してください。設定しない場合、動画のステータスはアップロード済みのままとなり、メディアを再生できません。

    • WorkflowIdとTemplateGroupIdの両方を指定した場合、WorkflowIdが優先されます。詳細については、ワークフローを参照してください。

    • このパラメーターは非同期タスクをトリガーします。リクエストが送信された後、タスクはバックグラウンド処理のためにキューに入れられ、すぐには完了しません。

    ca3a8f6e49c87b65806709586****
    UserData

    string

    任意

    メッセージコールバックの設定を含む、JSON 文字列形式のカスタム設定。詳細については、 UserData を参照してください。

    説明

    この操作は登録時にコールバックを生成しません。ただし、UserDataで指定されたコールバックアドレスは、それらのタスクに別のコールバックが指定されない限り、登録されたメディアに対する後続のトランスコーディングまたはスナップショットタスクに使用されます。

    {"Extend":{"localId":"****","test":"www"}}
    WorkflowId

    string

    任意

    ワークフローのID。ApsaraVideo VODコンソールにログインし、左側のナビゲーションペインで設定管理 > メディア処理設定 > ワークフローを選択して、ワークフローIDを確認できます。

    説明

    • WorkflowIdとTemplateGroupIdの両方を指定した場合、WorkflowIdが優先されます。詳細については、ワークフローを参照してください。

    • このパラメーターは非同期タスクをトリガーします。リクエストが送信された後、タスクはバックグラウンド処理のためにキューに入れられ、すぐには完了しません。

    637adc2b7ba51a83d841606f8****
    EnableFirstFrameCover

    boolean

    任意

    GenerateThumbnail

    boolean

    任意

    RegisterMetadata

    登録するメディアのメタデータを指定します。

    パラメーター型必須説明
    FileURLStringはいソースファイルURL。GetMezzanineInfo 操作を呼び出してURLを取得できます。
    URLの長さは1,024バイト以下で、ファイル名はグローバルに一意である必要があります。同じ名前のファイルを登録すると、関連付けられた一意のメディアIDが返されます。URLは、OSSバケットのパブリックエンドポイントの後にオブジェクト名を続けた形式です。
    TitleStringはいメディアのタイトル。タイトルは最大 128バイトで、UTF-8エンコードである必要があります。
    DescriptionStringいいえメディアの説明。説明は最大 1,024バイトで、UTF-8エンコードである必要があります。
    TagsStringいいえメディアタグ。最大 16 個のタグをカンマ（,）で区切って指定できます。各タグは最大 32バイトで、UTF-8エンコードである必要があります。
    CoverURLStringいいえカバー画像のURL。URLの長さは1,024バイト以下である必要があります。
    CateIdLongいいえカテゴリID。以下のいずれかの方法でIDを取得できます。
    ApsaraVideo VODコンソールにログインします。左側のナビゲーションペインで、設定管理 > メディアアセット設定 > カテゴリ管理を選択して、カテゴリIDを確認します。
    AddCategory 操作を呼び出して、カテゴリを作成します。レスポンスのCateIdの値がカテゴリIDです。
    GetCategories 操作を呼び出して、カテゴリを照会します。レスポンスのCateIdの値がカテゴリIDです。
    ReferenceIdStringいいえカスタムID。小文字、大文字、数字、ハイフン（-）、アンダースコア（_）を含めることができます。IDは6～64 文字で、アカウント内で一意である必要があります。

    レスポンスフィールド

    フィールド

    型

    説明

    例

    object

    レスポンスパラメーター。

    RequestId

    string

    リクエストID。

    14F43C5C-8033-448B-AD04F64E5098****
    FailedFileURLs

    array

    登録に失敗したファイルのURLリスト。

    string

    登録に失敗したファイルのURLリスト。

    ["http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4"]
    RegisteredMediaList

    array<object>

    新規登録されたファイルと既に登録済みのファイルの両方を含む、リクエストで正常に処理されたすべてのメディアのリスト。

    object

    登録の詳細。

    NewRegister

    boolean

    メディアが新規登録されたか、既に登録済みかを示します。

    • true：新規登録。

    • false：登録済み。

    false
    FileURL

    string

    OSSファイルのURL。

    http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4
    MediaId

    string

    メディアID。音声または動画ファイルの場合、このIDはVideoIdに対応します。

    d97af32828084d1896683b1aa38****

    例

    成功レスポンス

    JSONJSON

    {
  "RequestId": "14F43C5C-8033-448B-AD04F64E5098****",
  "FailedFileURLs": [
    "[\"http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_03.mp4\"]"
  ],
  "RegisteredMediaList": [
    {
      "NewRegister": false,
      "FileURL": "http://****.oss-cn-shanghai.aliyuncs.com/vod_sample_01.mp4",
      "MediaId": "d97af32828084d1896683b1aa38****"
    }
  ]
}

    エラーコード

    完全なリストについては、「エラーコード」をご参照ください。

    変更履歴

    完全なリストについては、「変更履歴」をご参照ください。