メインコンテンツまでスキップ

エンコーディングプロファイル管理

バージョン別機能範囲のご案内
  • v2 非対応: エンコーディングプロファイル管理機能は v2 では対応していないため、v1 から v3 へ直接移行する必要があります。
  • 共通認証: すべてのバージョンの API はクエリストリングパラメータ（?access_token=）による共通認証方式を使用します。エラー判定基準に関する共通仕様は、API v3 移行ガイドのコア変更点セクションをご参照ください。
エンコーディングプロファイル管理 API v3 リファレンスへ

共通変更事項 (v1 → v3)​

  • レスポンスラッパー構造: v1 の配列返却位置である result.items 構造が、v3 では最上位の data 配列形式に標準化されました。
  • データ型の変更: v1 で整数（0 または 1）として返却されていた論理属性フィールド（is_default_preset, is_optional, is_video_ratio, is_video_vertical_flip, is_video_horizontal_flip）が、v3 では Boolean 型に変更されました。
  • グループ情報のオブジェクト化: v1 のフラット構造（media_profile_group_key, media_profile_group_name）が、v3 ではネストされたオブジェクト（group.{key, name}）構造に変更されました。
  • 識別子タイプの変更: プロファイルを識別する固有値が、整数型の media_profile_id から文字列形式の media_profile_key に変更されました。

対応フォーマット全体照会​

  • 既存 (v1): GET /media/media_profile/profile_format
  • 変更 (v3): GET /media-profiles/format
変更事項

レスポンス構造が標準オブジェクト配列構造（{ "data": [{...}] }）に変更されました。内部の返却フィールド名（video_bitrate, video_framerate, audio_bitrate, audio_samplerate）は従来と同様に維持されます。

エンコーディングプロファイルプリセット一覧照会​

アカウントに登録されたプロファイルではなく、選択可能な全候補プリセットカタログを照会します。

  • 既存 (v1): GET /media/media_profile/preset
  • 変更 (v3): GET /media-profiles/preset
変更事項
  • 上記の 共通変更事項（ラッパー、Boolean 型、グループ構造化）がすべて適用されます。
  • v3 では、オーディオ属性およびファイル可否を識別するための bitrate_mode, is_audio_file フィールドが追加されました。
レスポンス構造の詳細

レスポンス構造仕様（data 配列内オブジェクトのフィールド名）​

  • 基本属性: id, key, name, is_audio_file, is_default_preset, is_optional, container_format, bitrate_mode
  • ビデオ属性: video_codec, video_bitrate, video_width, video_height, video_framerate, video_rotate_degree, video_overlay_position, video_overlay_path, is_video_ratio, is_video_vertical_flip, is_video_horizontal_flip
  • オーディオ属性: audio_codec, audio_bitrate, audio_samplerate, audio_channel, audio_volume_control
  • グループ情報: group オブジェクト（key, name）

エンコーディングプロファイルグループ一覧照会​

  • 既存 (v1): GET /media/media_profile_group/index
  • 変更 (v3): GET /media-profile-groups
レスポンス構造の詳細

レスポンス構造対照​

v1​

{ "error": 0, "result": { "count", "order", "items" } }

v3​

{ "data": [{ "key", "name" }] }

エンコーディングプロファイル一覧照会​

プリセットカタログとは異なり、アカウントに実際に登録・有効化されたプロファイル一覧を照会します。

  • 既存 (v1): GET /media/media_profile/index
  • 変更 (v3): GET /media-profiles
変更事項
  • グループ/カテゴリ情報の返却方式変更: v1 では media_profile_group_key と _name フィールドで情報を提供していましたが、v3 では配列（categories[].{key, name}）構造を通じて所属カテゴリ情報を返却します。
  • 新規返却フィールド: v3 では、プロファイルの有効化状態を示す status 属性と、所属カテゴリ情報を含む categories[] 配列がレスポンスデータに追加されました。
リクエストパラメータおよびレスポンス構造の詳細

リクエストクエリパラメータ​

v1 および v3 のいずれも、id または name を基準にデータの並び順を設定する order パラメータをサポートします。

レスポンス構造仕様​

v3 の エンコーディングプロファイルプリセット一覧照会 のレスポンス構造をほぼ維持しつつ、下部に status フィールドと categories[] 配列オブジェクトが追加された形式です。

エンコーディングプロファイル詳細仕様照会​

  • 既存 (v1): 非対応（単体照会エンドポイントなし）
  • 変更 (v3): GET /media-profiles/{media_profile_key}

レスポンス構造仕様​

エンコーディングプロファイル一覧照会 の配列内の単一オブジェクトのフィールド構成と同じです。

新規エンコーディングプロファイル作成​

  • 既存 (v1): POST /media/media_profile/create
  • 変更 (v3): POST /media-profiles
リクエストボディおよびレスポンス構造の詳細

リクエストボディ​

v1 および v3 のいずれも media_profile_preset_id（Integer）フィールドを必須で送信する必要があり、構造は同じです。

レスポンス構造対照​

v1​

成功時に固有オブジェクト情報はなく、メッセージのみを返却します。レスポンスメッセージ内にスペルミス（sucessfully）が存在します。

{ "error": 0, "message": "Sucessfully created" }

v3​

HTTP 201 Created コードとともに、生成された全体プロファイルオブジェクト（エンコーディングプロファイル一覧照会の仕様）と status フィールドを返却します。

エンコーディングプロファイル詳細仕様修正​

  • 既存 (v1): POST /media/media_profile/edit/{media_profile_id}
  • 変更 (v3): PUT /media-profiles/{media_profile_key}
変更事項
  • メソッドおよび識別子タイプの変更: v1 の POST メソッド（識別子：整数 id）が、v3 では PUT メソッド（識別子：文字列 key）に変更されました。
  • データ型に関する注意: v1 ではリクエストボディのフィールドがほとんど文字列型として処理されていましたが、一覧照会レスポンスは整数型で返却される型の不一致現象がありました。v3 では明確な型（Integer、String、Enum）の制約が適用されます。
  • 修正可能範囲の拡大: v1 では名前、ビットレート、解像度、フレームレート、オーディオ属性程度しか修正できませんでしたが、v3 では video_codec, video_ratio, container_format, bitrate_mode, status 情報まで修正できるよう機能が拡張されました。
リクエストボディの詳細
フィールドデータ型必須有無v3 許容値および制約条件
nameString必須変更するプロファイル名称
video_codecString任意H.264, H.265, AV1（ただし、H.265, AV1 は HW エンコーディング時のみ許可）
video_ratioString任意16:9, 16:10, 4:3, 21:9, Custom, Auto（トランスコーダー 2.0 環境）
video_widthInteger必須ビデオ幅解像度（偶数のみ許可）
video_heightInteger必須ビデオ高さ解像度（偶数のみ許可）
container_formatString任意mp4, MP4
bitrate_modeString任意cbr（固定ビットレート）、vbr（可変ビットレート）
video_bitrateInteger必須ビデオビットレート値
video_framerateInteger任意Enum（10〜60の範囲内で指定）
audio_codecString任意AAC, MP3
audio_bitrateInteger任意Enum（48〜320の範囲内で指定）
audio_samplerateInteger任意Enum（11025〜48000の範囲内で指定）
statusInteger任意プロファイル有効化状態（0 無効、1 有効）

プロファイル–カテゴリ連携​

  • 既存 (v1): 非対応
  • 変更 (v3): POST /media-profiles/{media_profile_key}/categories/{category_key}/attach

レスポンス構造仕様​

成功時に status 状態フィールドとともに、連携が更新されたプロファイル詳細オブジェクト（エンコーディングプロファイル一覧照会のレスポンス構造と同じ）を返却します。

プロファイル–カテゴリ連携解除​

  • 既存 (v1): 非対応
  • 変更 (v3): DELETE /media-profiles/{media_profile_key}/categories/{category_key}/detach

レスポンス構造仕様​

成功時に連携解除が反映されたプロファイル詳細オブジェクトを返却します。（レスポンス構造内に status フィールドは含まれません。）