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

字幕管理

共通変更事項のご案内
  • 共通変更事項: v1 では主に POST メソッドとリクエストボディを使用していましたが、v2 および v3 からは URL パス（Path）ベースの REST API 構造へ転換されました。v2 URL に含まれていた /vod プレフィックスは v3 で削除され、言語識別子は整数型の language_id から文字列形式の language_code（例: ko）に変更されました。
  • 共通認証: すべてのバージョンの API はクエリストリングパラメータ（?access_token=）による共通認証方式を使用します。エラー判定基準に関する共通仕様は、API v3 移行ガイドの コア変更点 セクションを参照してください。
字幕管理 API v3 リファレンスへ移動

字幕リスト照会​

  • 既存 (v1): POST /media/subtitle/index
  • 既存 (v2): GET /vod/media-contents/{upload_file_key}/subtitles
  • 変更 (v3): GET /media-contents/{upload_file_key}/subtitles
変更事項
  • HTTP メソッド転換: POST メソッド（リクエストボディ送信）から GET メソッド（パスパラメータ送信）に変更されました。
  • 識別子パラメータ変更: v1 の media_content_key パラメータが v3 では upload_file_key に変更されました。
  • フィールド名マッピング: 識別子キーが subtitle_id から id に、言語キーが language_id から language_code に、subtitle_url が srt_url にそれぞれ名称が変更されました。
リクエストパラメータおよびレスポンス構造の詳細

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

パラメータデータタイプ説明および許容値
nameString字幕名フィルタリング
language_codeString字幕言語フィルタリング（ko: 韓国語、en: 英語）
statusInteger字幕公開設定フィルタリング（0: 非公開、1: 公開）

レスポンス構造対照​

v1​

{
  "error": 0,
  "result": {
    "subtitle_id": 123,
    "name": "...",
    "language_id": 1,
    "subtitle_url": "...",
    "vtt_url": "..."
  }
}

v2/v3​

{
  "data": [
    {
      "id": 1234,
      "name": "subtitle1",
      "kind": "main",
      "status": true,
      "language_code": "ko",
      "vtt_url": "https://...",
      "srt_url": "https://...",
      "position": 1
    }
  ]
}
  • 参考: システム内部で .srt ファイルを .vtt フォーマットへ自動変換する機能は提供していません。vtt_url フィールドに値がレスポンスされるようにするには、必ず拡張子が .vtt のファイルを直接アップロードする必要があります。

字幕登録（テキスト直接入力）​

  • 既存 (v1): 非対応（ファイルアップロード方式のみ提供）
  • 既存 (v2): POST /vod/media-contents/{upload_file_key}/subtitles
  • 変更 (v3): POST /media-contents/{upload_file_key}/subtitles
リクエストボディの詳細

リクエストボディ​

フィールドデータタイプ必須有無説明および許容値
bodyString必須実際の字幕テキスト
typeString必須字幕ファイル規格（vtt または srt）
kindString必須字幕タイプ（main: メイン字幕、sub: サブ字幕）
statusInteger任意字幕公開設定（0: 非公開、1: 公開）
nameString必須字幕名
language_codeString必須字幕言語コード（ko: 韓国語、en: 英語）

字幕ファイルの新規アップロード​

  • 既存 (v1): POST /media/subtitle/upload
  • 既存 (v2): POST /vod/media-contents/{upload_file_key}/subtitles/upload
  • 変更 (v3): POST /media-contents/{upload_file_key}/subtitles/upload
変更事項
  • リクエストフォーマット変更: multipart/form-data 形式を使用し、v1 で伝達していた language_id の代わりに language_code を送信する必要があります。
  • レスポンスデータ仕様の高度化: v1 は成功時に生成された識別子のみを { "result": { "subtitle_id" } } 形式で返しましたが、v2 および v3 は登録された字幕オブジェクト全体（字幕リスト照会のレスポンス仕様と同じ）を返します。
リクエストボディの詳細

リクエストボディ（Multipart Body）​

フィールドデータタイプ必須有無説明
fileBinary必須字幕ファイル
nameString任意字幕名
language_codeString必須字幕言語コード
kindString必須字幕タイプ（main: メイン字幕、sub: サブ字幕）
statusInteger任意字幕公開設定（0: 非公開、1: 公開）

字幕ファイルの更新​

  • 既存 (v1): POST /media/subtitle/update
  • 既存 (v2): POST /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}/upload
  • 変更 (v3): POST /media-contents/{upload_file_key}/subtitles/{subtitle_id}/upload
機能案内

multipart/form-data 規格を使用し、リクエストボディのパラメータ仕様は 字幕ファイルの新規アップロード 項目と完全に同一です。リクエスト時に status フィールドを省略した場合、既存の設定値がそのまま維持され、レスポンスは更新された字幕オブジェクト情報を返します。

字幕情報の照会​

  • 既存 (v1): 非対応
  • 既存 (v2): GET /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • 変更 (v3): GET /media-contents/{upload_file_key}/subtitles/{subtitle_id}
レスポンス構造の詳細

レスポンス構造仕様​

v3 の場合、システム実装によって status（字幕公開有無）属性が含まれることがあります。

{
  "data": {
    "id": 0,
    "name": "string",
    "kind": "string",
    "language_code": "string",
    "vtt_url": "string",
    "srt_url": "string",
    "position": 0
  }
}

字幕情報の修正​

  • 既存 (v1): POST /media/subtitle/update
  • 既存 (v2): PUT /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • 変更 (v3): PUT /media-contents/{upload_file_key}/subtitles/{subtitle_id}
変更事項
  • エンドポイント分離: v1 ではファイル置き換え（Upload）機能とメタ属性修正（Update）機能を 1 つのエンドポイントで処理していましたが、v3 からは HTTP PUT メソッドを使用する別の API として完全に分離されました。
  • リクエストパラメータ: 字幕登録（テキスト直接入力）のリクエストボディパラメータ仕様（body、type、kind、name、language_code、status）と同じ構造を使用します。

字幕削除​

  • 既存 (v1): POST /media/subtitle/delete
  • 既存 (v2): DELETE /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • 変更 (v3): DELETE /media-contents/{upload_file_key}/subtitles/{subtitle_id}
変更事項
  • HTTP メソッド転換: HTTP メソッドが POST から DELETE に変更されました。
レスポンス構造の詳細

レスポンス構造対照​

  • v1: { "error": 0, "message": "...", "result": true | false }
  • v2: HTTP 204 No Content
  • v3: 成功時に空のデータ配列構造である { "data": [] } を返します。

字幕表示順序の変更​

変更事項

v2 では特定の字幕を基準に前後（相対的位置）へ移動する方式を採用していましたが、v3 では目標位置を直接指定して入れ替える方式と、最上段/最下段へ移動させる方式に変更されました。

動作区分v2v3
特定位置非対応PUT .../subtitles/{subtitle_id}/move
  • （リクエストボディ）id: 目標位置の字幕ID
特定字幕の前後
  • PUT .../move-before
  • PUT .../move-after
非対応
最上段PUT .../move-firstPUT .../move-first
最下段PUT .../move-lastPUT .../move-last

レスポンス構造仕様​

変更された順序値が反映された該当字幕の詳細データ（字幕リスト照会のレスポンス仕様と同じ）オブジェクトを返します。

字幕対応言語リストの照会​

  • 既存 (v1): GET /media/subtitle/languages
  • 既存 (v2): GET /vod/languages
  • 変更 (v3): GET /languages
変更事項

v3 では use_subtitle パラメータ（true または false）をクエリで提供し、字幕用言語のみをフィルタリングして照会できます。

レスポンス構造の詳細

レスポンス構造対照​

  • v1: { "error": 0, "message": "...", "result": object }
  • v2: { "data": [{ "name": "...", "code": "..." }] }
  • v3: { "data": [ApiCommonLanguage object] }（API リファレンスの言語リスト照会を参照してください。）