Kollus VOD API v3 マイグレーションガイド

Kollus VOD API v1, v2 サービスをご利用のお客様が v3 へ安定的に移行するための主要な変更点とエンドポイントのマッピング情報をご案内します。 以下の 5つのコア変更点 をまず確認した上で、機能別エンドポイントインデックス から各機能の詳細マッピングページへ移動して作業を進めてください。

サービス終了のご案内

Kollus VOD API v1, v2 は2027年6月30日をもってサポートが全面終了となります。安定したサービス運用のため、期限内に v3 へのマイグレーションを完了してください。

コア変更点

すべてのエンドポイントに共通して適用される最も重要な変更点です。マイグレーションのコード設計時に最初に反映する必要があります。

1. Base URL の変更

アップロードエンドポイントを除くすべての API のホストドメインが変更されます。

• 既存 (v1): api.kr.kollus.com/0
• 既存 (v2): api-vod-kr.kollus.com/api/v0
• 変更後 (v3): c-api-kr.kollus.com/api
• 注意: アップロード機能は別ホストである upload.kr.kollus.com を使用します。

2. 標準 HTTP メソッドの適用

v1 の POST 一方向構造から、RESTful 標準仕様に準拠した HTTP メソッドへ転換されました。

• 参照: GET
• 生成: POST
• 修正: PUT
• 削除: DELETE

3. 識別子タイプの変更（Integer → String）

すべてのリソースの識別子（ID）形式が整数型から文字列（Key）形式に変更され、言語コードなども標準仕様に従います。

• media_content_id (Integer) → upload_file_key (String)
• media_profile_id (Integer) → media_profile_key (String)
• language_id (例: 2) → language_code (例: "ko")

4. レスポンス構造および成功判定基準の変更

成功可否を判定する方式が HTTP ステータスコードに一元化され、レスポンスデータ構造（フォーマット）が簡素化されました。

• 成功判定: 既存の error === 0 チェック → HTTP ステータスコード（200 または 201） チェック
• レスポンスフォーマット: { error, message, result } → { data } 構造でラッピング

v2 エラー処理の例外事項

HTTP 200 レスポンス内のerror: 1ルールは v1 にのみ該当します。v2 は HTTP 標準ステータスコード（404、422 など）と Laravel スタイルの { message, errors } 構造でレスポンスします。

5. パスパラメータ構造の変更

チャンネルとコンテンツ間の関係設定時、従来リクエストボディに含まれていた識別子の相互作用が URL パス（Path）構造に変更されました。

• 既存 (v1/v2): channel_key 情報をリクエストボディに含めて送信
• 変更後 (v3): channel_key と upload_file_key をいずれも URL パスパラメータに含めてリクエスト（参考文書: チャンネル管理）

機能別エンドポイントインデックス

マイグレーションが必要な機能のカテゴリを選択すると、詳細マッピングページへ移動します。各詳細ページでは、既存バージョンとの変更点を優先的に提供します。

カテゴリ	含まれる機能	備考
共通	国、言語、タイムゾーンリスト参照	国およびタイムゾーンリスト参照は v3 新規機能
カテゴリ管理	カテゴリリスト参照/生成/修正/削除、チャンネル連携/連携解除	v2 はカテゴリ-チャンネル連携/連携解除機能のみサポート
チャンネル管理	チャンネルリスト参照/生成/修正/削除、コンテンツまたはプレイヤースキン連携、Callback およびセキュリティ	キーの位置に注意
メディアコンテンツキー管理	コンテンツキー情報参照、有効性検証、コンテンツ割り当て	コンテンツキー交換機能は v3 で廃止
メディア認証管理	Kollus 暗号化、ユーザーキー生成/再発行/削除、ウォーターマーキング識別コード参照	v2 非対応
コンテンツ管理	コンテンツリスト参照/詳細参照、修正/削除、有効化/無効化、カテゴリ変更、アップロード URL 生成、ポスター/原本ファイルダウンロード	メタデータ参照/修正、スナップショット生成/ダウンロード（v2 専用）機能は v3 で廃止
トランスコーディング管理	トランスコーディング進行状況参照、追加トランスコーディング作業生成、トランスコーディングファイル参照/ダウンロード/有効化/無効化/削除	v2 非対応
AI サービス	AI字幕生成、AI要約・チャプター参照/生成、AI倍速転換	v3 新規機能
字幕管理	字幕リスト参照/詳細参照、登録/アップロード/修正/削除、表示順序変更、対応言語リスト参照	テキスト直接入力登録および字幕詳細参照は v2 からサポート
ブックマーク管理	ブックマークリスト参照（アップロードファイルキー/メディアコンテンツキー基準）、追加/修正/削除	v1 は非対応、v2 はリスト参照のみ限定的にサポート
エンコーディングプロファイル管理	対応仕様/プリセット/グループ参照、プロファイルリスト参照/詳細参照/生成/修正、カテゴリ連携/解除	v2 非対応
重複再生遮断管理	重複再生遮断記録参照、許可デバイス参照/削除/全て初期化	v3 新規機能
プレイヤー管理	プレイヤースキンリスト参照/削除、プレイヤーイベントリスト参照/削除	v3 新規機能
統計	全体/チャンネルコンテンツ視聴ランキング参照、日別統計参照	視聴ランキング参照は最上位キーとしてresult_dataを使用
タグ管理	タグ別コンテンツリスト参照、タグ追加/削除	v1 専用

マイグレーション技術サポート

マイグレーション中に問題が発生した場合、またはご不明な点がある場合は、営業担当者(jp_sales@catenoid.net)までお問い合わせください。 迅速かつ正確なサポートのため、お問い合わせの際は以下の必須情報を併せてご記載ください。

必須記載事項

1. 現在使用中の API バージョン（v1 または v2）
2. 問題が発生しているエンドポイント URL
3. エラーログ、レスポンスメッセージおよび再現手順