コンテンツ管理

お知らせ

このドキュメントは機械翻訳で作成された下書きであり、現在レビュー中です。機械翻訳の特性上、一部の内容が不正確であったり、韓国語の原文と異なる場合があります。より正確な情報については、韓国語のドキュメントをご参照ください。

コンテンツ管理 API v3 リファレンスへ移動

バージョン別機能範囲のご案内

共通認証: すべてのバージョンの API は、クエリ文字列パラメータ（?access_token=）による共通認証方式を使用します。エラー判定基準に関する共通仕様は、API v3 マイグレーションガイドの主な変更点セクションを参照してください。
トランスコーディング: トランスコーディングの進行状況照会およびトランスコーディングファイルに関する仕様は、トランスコーディング管理ドキュメントを参照してください。

全コンテンツリスト取得

旧 (v1): GET /media/library/media_content
旧 (v2): 非対応（チャンネル別コンテンツリスト取得のみ対応）
変更後 (v3): GET /media-contents

変更事項

レスポンス内データ構造の変更: レスポンスオブジェクトの配列返却位置が、従来の result.item[] から data[] へと標準化され、ページング処理のために pagination オブジェクトが追加されました。
配列項目フィールド: 配列内の個別コンテンツアイテムの詳細フィールド仕様は、下記の「コンテンツ情報取得」と同一です。

チャンネル別コンテンツリスト取得

チャンネル管理ドキュメントのチャンネル別コンテンツリスト取得セクションを参照してください。

カテゴリ別コンテンツリスト取得

旧 (v1/v2): 非対応
変更後 (v3): GET /categories/{category_key}/media-contents

リクエストパラメータおよびレスポンス構造の詳細

リクエストパラメータ

リクエストパラメータ仕様は、全コンテンツリスト取得 API の構成と完全に一致します。

レスポンス構造仕様

{
  "status": 200,
  "data": [
    {
      "title": "string",
      "upload_file_key": "string"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 100
  }
}

コンテンツアップロード URL 生成

旧 (v1): POST /media_auth/upload/create_url
旧 (v2): 非対応
変更後 (v3): POST /upload/create-url

変更事項

アップロード処理ホスト: 発行された upload_url は、共通ドメインアドレスではなく、アップロード専用ドメインである https://upload.kr.kollus.com を対象として返却されます。
フィールド名の変更: v1 の will_be_expired_at フィールドが、v3 では expired_at に変更されました。

リクエストボディおよびレスポンス構造の詳細

リクエストボディ

フィールド	データ型	必須	説明
`expire_time`	Integer	任意	アップロード URL の有効時間（デフォルト値: 600秒、最大値: 21600秒）
`title`	String	必須	コンテンツタイトル
`category_key`	String	任意	分類対象カテゴリの固有識別値
`is_encryption_upload`	Integer	任意	暗号化設定（`0`: 非暗号化（一般）コンテンツ、`1`: 暗号化コンテンツ）
`is_audio_upload`	Integer	任意	オーディオ専用コンテンツ設定（`0`: ビデオを含む、`1`: オーディオ専用）
`use_ai_script`	Integer	任意	AI 倍速適用有無
`use_ai_subtitle`	Integer	任意	AI 字幕生成有無
`use_ai_outline`	Integer	任意	AI 要約・チャプター生成有無
`ai_subtitle_language`	String	任意	AI 字幕言語設定（動画またはオーディオの主要使用言語）
`ai_subtitle_status`	Integer	任意	AI 字幕公開設定（`0`: 非公開、`1`: 公開）
`ai_subtitle_kind`	Integer	任意	AI 字幕タイプ設定（`0`: メイン字幕、`1`: サブ字幕）

レスポンス構造対照

{
  "error": 0,
  "message": "success",
  "result": {
    "upload_url": "https://upload.kr.kollus.com/old-upload-path",
    "progress_url": "https://upload.kr.kollus.com/old-progress-path",
    "upload_file_key": "v1_file_key",
    "will_be_expired_at": 1672531199
  }
}

{
  "status": 201,
  "data": {
    "upload_url": "https://upload.kr.kollus.com/v3-upload-path",
    "progress_url": "https://upload.kr.kollus.com/v3-progress-path",
    "upload_file_key": "v3_file_key",
    "expired_at": 1672531199
  }
}

コンテンツ情報取得

旧 (v1): GET /media/library/media_content/{upload_file_key}
旧 (v2): GET /vod/media-contents/{upload_file_key}
変更後 (v3): GET /media-contents/{upload_file_key}

変更事項

v1 → v3 変換: 全体的なフラット構造とフィールド名は維持されますが、データ型が大幅に変更されました。（例: Integer から Boolean への変換、Unix Timestamp から ISO8601 文字列への型変更）
v2 → v3 変換: v2 で複数階層にネストされていたサブオブジェクト（kind、category、original_file）構造が、v3 では直感的なフラット構造に変更されました。
v1 専用フィールドの削除: 従来の v1 レスポンスに含まれていた transcoding_files、channels、metadata フィールドは、v3 で完全に削除されました。

レスポンスフィールド詳細マッピング

フィールド	v1 仕様	v2 仕様	v3 仕様	マイグレーション参考事項
`kind`	Integer + `kind_name`	`kind.{type, value}` オブジェクト	Integer + `kind_name`	v2 の構造のみネストされたオブジェクト型で返却される
`duration`	String	Integer（単位: 秒）	String（HH:MM:SS）	v3 はタイムコード形式を使用
`category`	`category_name` / `_key`（フラット）	`category.{id, key, name, level_path}`（ネスト）	`category_name` / `_key`（フラット）	v3 は v1 と同一のフラット構造で返却
`original_file`	`original_file_name` / `_size`（フラット）	`original_file.{name, size}`（ネスト）	フラット構造で返却	ファイルサイズ形式: String（v1）→ Integer（v2/v3）
`use_encryption`	Integer（0 または 1）	Boolean	Boolean	v1 と比べ、整数型変数が Boolean 型に変更
`status`	Integer（例: 1）	Boolean	Boolean	v1 と比べ、整数型変数が Boolean 型に変更
`transcoded_at`, `created_at`, `updated_at`	Unix Integer	ISO8601 文字列	ISO8601 文字列	-
*`vr_`**	非対応	`vr_information.{type, value}`	`vr_info.{projection_type, stereo_mode}`	v2 と比べ、v3 でキー名が変更されている
`human_readable_original_file_size`	提供	非対応	提供	データの可読性を考慮したサイズ変換値（例: "823.5MB"）
`media_information`	3分類（file, video, audio）	2分類（audio が欠落）	3分類（file, video, audio）	v3 は v1 と同様に3分類情報を完全に提供
`transcoding_stage`	提供	非対応	提供	詳細コード仕様はトランスコーディング管理ドキュメントを参照
`transcoding_stage_name`	提供	非対応	提供	詳細コード仕様はトランスコーディング管理ドキュメントを参照
`poster_url`, `snapshot_url`	提供	非対応	提供	代表画像アドレス情報フィールドの追加
`is_passthrough`	-	-	Boolean	v3 で追加されたコンテンツ状態/マッピングフィールド
`media_content_keys[]`	-	-	Array	v3 で追加されたコンテンツ状態/マッピングフィールド

コンテンツ情報修正

旧 (v1): POST /media/media_content/update
旧 (v2): PUT /vod/media-contents/{upload_file_key}
変更後 (v3): PUT /media-contents/{upload_file_key}

変更事項

対象識別方式: v1 はリクエストボディ内の固有識別用整数 id で対象を指定していましたが、v3 では URL パスの {upload_file_key} を通じて識別します。
VR 設定の構造化: v2 ではフラットパラメータ（projection_type、stereo_mode）で送信していましたが、v3 では vr 上位オブジェクト配下のフィールド（vr.projection_type、vr.stereo_mode）としてまとめて送信する必要があります。

リクエストボディおよびレスポンス構造の詳細

リクエストボディ

v1: id（必須）+title
v2: title, projection_type（rectangular/equirectangular）, stereo_mode（mono）
v3: title, vr.projection_type, vr.stereo_mode

レスポンス構造対照

v1: { error, message }
v2: { data: ApiVodMediaContent }
v3: { "data": ApiVodMediaContent, "status": "ok" }

コンテンツメタデータ取得

旧 (v1): GET /media/library/get_metadata/{upload_file_key}
旧 (v2): 非対応
変更後 (v3): 非対応

メタデータサービスの廃止

v3 では、メタデータ専用の取得エンドポイントは提供されず、コンテンツ情報取得レスポンス内部の metadata 詳細フィールドまで一貫して廃止されました。

コンテンツメタデータ修正

旧 (v1): POST /media/library/update_metadata/{upload_file_key}
旧 (v2): 非対応
変更後 (v3): 非対応

メタデータサービスの廃止

上記のメタデータ取得用 API の廃止方針に従い、メタデータ情報修正機能も v3 で廃止されました。

コンテンツ削除

旧 (v1/v2): 非対応（コンテンツの物理削除機能が存在せず、有効/無効の制御によってのみライフサイクルを管理していました）
変更後 (v3): DELETE /media-contents/{upload_file_key}

レスポンス構造の詳細

レスポンス構造仕様

{
  "data": [],
  "status": "ok"
}

コンテンツカテゴリ変更

旧 (v1): POST /media/library/change_category/{upload_file_key}（ボディに category_key を含む）
旧 (v2): 非対応
変更後 (v3): PUT /media-contents/{upload_file_key}/categories/{category_key}

変更事項

HTTP メソッドの変更: HTTP メソッドが POST から PUT に変更されました。
パラメータ位置の移動: v1 でリクエストボディに含めて送信していた category_key が、v3 ではパスパラメータに統合されました。

レスポンス構造の詳細

v1: { error, message }（別途の結果値データなし）
v3: { "data": ApiVodMediaContentCategory, "status": "ok" }（新規カテゴリがマッピングされた結果情報を返却）

コンテンツ無効化

旧 (v1): POST /media/library/set_disable/{upload_file_key}
旧 (v2): 非対応
変更後 (v3): PUT /media-contents/{upload_file_key}/disable

変更事項

HTTP メソッドの変更: HTTP メソッドが POST から PUT に変更されました。
レスポンスの標準化: ApiVodMediaContentStatus オブジェクト構造で返却されます。

コンテンツ有効化

旧 (v1): POST /media/library/set_enable/{upload_file_key}
旧 (v2): 非対応
変更後 (v3): PUT /media-contents/{upload_file_key}/enable

変更事項

HTTP メソッドの変更: HTTP メソッドが POST から PUT に変更されました。
レスポンスの標準化: { "data": ApiVodMediaContentStatus, "status": "ok" } として返却されます。

ポスター画像アップロード

旧 (v1): POST /media/library/upload_poster/{upload_file_key}
旧 (v2): 非対応
変更後 (v3): POST /media-contents/{upload_file_key}/poster

変更事項

必須フィールド: v3 からは multipart/form-data ヘッダー形式を使用し、リクエストボディに file フィールド（Binary データ、必須）を渡す必要があります。
レスポンス構造: v1 の結果メッセージ返却方式から、v3 の規格化されたフォーマット（{ "data": [], "status": "ok" }）に置き換わります。

ポスター画像ダウンロード

旧 (v1/v2): 非対応
変更後 (v3): GET /media-contents/{upload_file_key}/poster/download

レスポンス構造の詳細

レスポンス構造仕様

{
  "data": {
    "expires": "2026-07-01T09:12:08+00:00",
    "download_url": "https://download.kr.kollus.com/path-to-poster-file"
  }
}

原本ファイルダウンロード

旧 (v1): 非対応
旧 (v2): GET /vod/media-contents/{upload_file_key}/original/download
変更後 (v3): GET /media-contents/{upload_file_key}/original-file/download

変更事項

パス名の変更: 従来 original として宣言されていたパス名が、original-file に変更されました。
フィールド情報の置換: v2 レスポンスオブジェクト内のダウンロード URI フィールド名である download_uri が、v3 で download_url に一括修正されました。

レスポンス構造仕様

{
  "data": {
    "expires": "2026-07-01T09:12:08+00:00",
    "download_url": "https://download.kr.kollus.com/path-to-original-file"
  }
}

スナップショット画像生成（v2 専用）

旧 (v1): 非対応
旧 (v2): POST /vod/media-contents/{upload_file_key}/snapshot
変更後 (v3): 非対応

スナップショットのリアルタイム抽出機能廃止

ユーザーがタイムコード地点を直接カスタムしてサムネイル画像を即座に再生成していた v2 のスクリプト機能は、v3 で完全に廃止されました。v3 では、メディアアップロード処理時に初期システムスケジューラーが自動生成する固定スナップショット情報（snapshot_url）のみ照会できます。

スナップショット画像ダウンロード（v2 専用）

旧 (v1): 非対応
旧 (v2): POST /vod/media-contents/get-snapshot-download-link（ボディに path を含む）
変更後 (v3): 非対応

スナップショットのリアルタイム抽出機能廃止

スナップショット画像生成機能の廃止に伴い、スナップショット画像ダウンロード API も v3 では提供されません。

全コンテンツリスト取得​

チャンネル別コンテンツリスト取得​

カテゴリ別コンテンツリスト取得​

リクエストパラメータ​

レスポンス構造仕様​

コンテンツアップロード URL 生成​

リクエストボディ​

レスポンス構造対照​

コンテンツ情報取得​

コンテンツ情報修正​

リクエストボディ​

レスポンス構造対照​

コンテンツメタデータ取得​

コンテンツメタデータ修正​

コンテンツ削除​

レスポンス構造仕様​

コンテンツカテゴリ変更​

コンテンツ無効化​

コンテンツ有効化​

ポスター画像アップロード​

ポスター画像ダウンロード​

レスポンス構造仕様​

原本ファイルダウンロード​

レスポンス構造仕様​

スナップショット画像生成（v2 専用）​

スナップショット画像ダウンロード（v2 専用）​

全コンテンツリスト取得

チャンネル別コンテンツリスト取得

カテゴリ別コンテンツリスト取得

リクエストパラメータ

レスポンス構造仕様

コンテンツアップロード URL 生成

リクエストボディ

レスポンス構造対照

コンテンツ情報取得

コンテンツ情報修正

リクエストボディ

レスポンス構造対照

コンテンツメタデータ取得

コンテンツメタデータ修正

コンテンツ削除

レスポンス構造仕様

コンテンツカテゴリ変更

コンテンツ無効化

コンテンツ有効化

ポスター画像アップロード

ポスター画像ダウンロード

レスポンス構造仕様

原本ファイルダウンロード

レスポンス構造仕様

スナップショット画像生成（v2 専用）

スナップショット画像ダウンロード（v2 専用）