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

トランスコーディング管理

お知らせ

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

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

トランスコーディング進行状況の照会​

  • 既存 (v1 - 一覧照会): GET /media/upload_file
  • 既存 (v1 - 単件照会): GET /media/media_content/view/{media_content_id}
  • 既存 (v2): 非対応
  • 変更後 (v3): GET /media-contents/{upload_file_key}/progress
変更点
  • エンドポイントの一本化: v1 では一覧照会と単件照会のエンドポイントが分離されていましたが、v3 では固有識別子である upload_file_key を基準とした単件照会エンドポイントに統合されました。
  • 識別子パラメータの注意: v1 の単件照会 API はパラメータとして watcher_file_key を使用していましたが、v3 ではアップロードファイルの固有識別子である upload_file_key を使用します。移行時のマッピングにご注意ください。
トランスコーディングステータスコードおよびレスポンス構造の詳細

トランスコーディングステータスコード (transcoding_stage)​

ステータスコードは v1 と v3 で同一に維持されます。 ステータスコード 11（トランスコーディング準備中）は、内部作業ループで 0（待機中）または 12（進行中）の状態を経た後、直ちに 21（完了）の状態へ遷移します。

ステータスコード説明
0待機中
11トランスコーディング準備中
1トランスコーディング開始
12トランスコーディング中
21トランスコーディング完了
51トランスコーディングエラー
52初期化失敗

レスポンス構造の比較​

  • v1 (単件照会)
{
  "error": 0,
  "message": "success",
  "result": {
    "media_content": { 
      "id": 123, 
      "watcher_file_key": "v1_key", 
      ...
      }
  }
}
  • v3
{
  "status": 200,
  "data": {
    "id": 12345,
    "title": "string",
    "upload_file_key": "string",
    "transcoding_stage": 21,
    "transcoding_stage_name": "Completed",
    "transcoding_progress": 100
  }
}

追加トランスコーディングジョブの生成​

特定のメディアコンテンツに対して、追加の画質/フォーマット(Profile)のトランスコーディングジョブを手動でスケジュールします。

  • 既存 (v1): POST /media/library/create_transcoding_file/{upload_file_key} (本文に profile_key を含む)
  • 既存 (v2): 非対応
  • 変更後 (v3): POST /media-contents/{upload_file_key}/media-profiles/{media_profile_key}/transcoding-jobs
変更点
  • パラメータ位置の変更: v1 でリクエスト本文に含めて送信していた対象プロファイルキー(profile_key)が、v3 では URL パスパラメータ(media_profile_key)に変更されました。
  • 制約事項（維持）: すでに進行中または完了しているファイルプロファイルは、追加トランスコーディング対象から除外されます。このビジネスロジックは v1 と v3 で同一です。

レスポンス構造の比較​

  • v1: { error, message } (生成されたジョブ識別子は提供されません)
  • v3: { "data": [{ "key": "new_job_key" }], "status": "ok" } (新しく生成されたトランスコーディングジョブ識別子の配列を返却)

トランスコーディングファイル管理 (v3 新規追加)​

  • 既存 (v1/v2): 非対応
  • 変更後 (v3): 新規エンドポイントを提供

新規 API エンドポイント一覧​

トランスコーディングファイルは、ファイル ID(transcoding_file_id)とエンコーディングプロファイルキー(profile_key)の2つの識別体系を通じて操作できます。

機能HTTPv3 エンドポイント
トランスコーディングファイル一覧照会GET/media-contents/{upload_file_key}/transcoding-files
トランスコーディングファイルダウンロード URL 生成GET/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/download
トランスコーディングファイル有効化 (ファイル ID 基準)PUT/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/enable
トランスコーディングファイル有効化 (プロファイルキー基準)PUT/media-contents/{upload_file_key}/media-profiles/{profile_key}/enable
トランスコーディングファイル無効化 (ファイル ID 基準)PUT/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/disable
トランスコーディングファイル無効化 (プロファイルキー基準)PUT/media-contents/{upload_file_key}/media-profiles/{profile_key}/disable
トランスコーディングファイル削除 (ファイル ID 基準)DELETE/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}
トランスコーディングファイル削除 (プロファイルキー基準)DELETE/media-contents/{upload_file_key}/media-profiles/{profile_key}
レスポンス構造の詳細

トランスコーディングファイル一覧照会/有効化/無効化のレスポンス仕様​

{
  "status": 200,
  "data": [
    {
      "id": 1,
      "media_profile_group_name": "PC1(16:9)",
      "media_profile_group_key": "pc1",
      "profile_name": "PC1(16:9) Normal",
      "profile_key": "pc1-normal",
      "filesize_bytes": 133306319,
      "media_information": {
        "file": { ... },
        "video": { ... },
        "audio": { ... }
      },
      "thumbnail_urls": {
        "big": "https://...",
        "small": "https://..."
      },
      "created_at": "2023-10-01T10:00:00Z",
      "updated_at": "2023-10-01T10:05:00Z"
    }
  ]
}

トランスコーディングファイルダウンロード URL 生成のレスポンス仕様​

{
  "data": {
    "expires": "2026-07-14T09:47:38+00:00",
    "download_url": "https://download.kr.kollus.com/path-to-transcoded-file"
  }
}

トランスコーディングファイル削除のレスポンス仕様​

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