Skip to main content

Subtitle Management

Notice

This document is a machine-translated draft and is currently undergoing review. Some content may be inaccurate or differ from the original Korean version. For the most precise information, refer to the Korean documentation.

Go to Subtitle Management API v3 Reference
Common changes
  • Common changes: v1 mainly used the POST method with a request body, but starting with v2 and v3, the API structure has been converted to a URL path-based REST API structure. The /vod prefix that was included in the v2 URL has been removed in v3, and the language identifier has been changed from the integer language_id to a string-based language_code (e.g., ko).
  • Common authentication: All API versions use a common authentication method via a query string parameter (?access_token=). For the common specification on error determination criteria, refer to the Core Changes section of the API v3 migration guide.

Retrieve subtitle list​

  • Existing (v1): POST /media/subtitle/index
  • Existing (v2): GET /vod/media-contents/{upload_file_key}/subtitles
  • Changed (v3): GET /media-contents/{upload_file_key}/subtitles
Changes
  • HTTP method conversion: Changed from the POST method (request body transmission) to the GET method (path parameter transmission).
  • Identifier parameter change: The media_content_key parameter in v1 has been changed to upload_file_key in v3.
  • Field name mapping: The identifier key has been renamed from subtitle_id to id, the language key from language_id to language_code, and subtitle_url to srt_url.
Request parameter and response structure details

Request query parameters​

ParameterData typeDescription and allowed values
nameStringFilter by subtitle name
language_codeStringFilter by subtitle language (ko: Korean, en: English)
statusIntegerFilter by subtitle visibility setting (0: private, 1: public)

Response structure comparison​

  • 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
    }
  ]
}
  • Note: The system does not provide a feature to automatically convert .srt files to the .vtt format. For the vtt_url field to be populated in the response, you must directly upload a file with the .vtt extension.

Register subtitle (direct text input)​

  • Existing (v1): Not supported (only file upload method provided)
  • Existing (v2): POST /vod/media-contents/{upload_file_key}/subtitles
  • Changed (v3): POST /media-contents/{upload_file_key}/subtitles
Request body details

Request body​

FieldData typeRequiredDescription and allowed values
bodyStringRequiredActual subtitle text
typeStringRequiredSubtitle file format (vtt or srt)
kindStringRequiredSubtitle type (main: main subtitle, sub: sub subtitle)
statusIntegerOptionalSubtitle visibility setting (0: private, 1: public)
nameStringRequiredSubtitle name
language_codeStringRequiredSubtitle language code (ko: Korean, en: English)

Upload new subtitle file​

  • Existing (v1): POST /media/subtitle/upload
  • Existing (v2): POST /vod/media-contents/{upload_file_key}/subtitles/upload
  • Changed (v3): POST /media-contents/{upload_file_key}/subtitles/upload
Changes
  • Request format change: Uses the multipart/form-data format, and language_code must be sent instead of language_id, which was used in v1.
  • Enhanced response data specification: v1 returned only the created identifier upon success, in the form { "result": { "subtitle_id" } }, but v2 and v3 return the entire registered subtitle object (same response specification as Retrieve subtitle list).
Request body details

Request body (Multipart Body)​

FieldData typeRequiredDescription
fileBinaryRequiredSubtitle file
nameStringOptionalSubtitle name
language_codeStringRequiredSubtitle language code
kindStringRequiredSubtitle type (main: main subtitle, sub: sub subtitle)
statusIntegerOptionalSubtitle visibility setting (0: private, 1: public)

Update subtitle file​

  • Existing (v1): POST /media/subtitle/update
  • Existing (v2): POST /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}/upload
  • Changed (v3): POST /media-contents/{upload_file_key}/subtitles/{subtitle_id}/upload
Feature description

Uses the multipart/form-data format, and the request body parameter specification is completely identical to the Upload new subtitle file item. If the status field is omitted in the request, the existing setting value is retained, and the response returns the updated subtitle object information.

Retrieve subtitle details​

  • Existing (v1): Not supported
  • Existing (v2): GET /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • Changed (v3): GET /media-contents/{upload_file_key}/subtitles/{subtitle_id}
Response structure details

Response structure specification​

For v3, the status (subtitle visibility) property may be included depending on system implementation.

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

Update subtitle information​

  • Existing (v1): POST /media/subtitle/update
  • Existing (v2): PUT /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • Changed (v3): PUT /media-contents/{upload_file_key}/subtitles/{subtitle_id}
Changes
  • Endpoint separation: In v1, the file replacement (Upload) feature and the metadata modification (Update) feature were handled by a single endpoint, but starting with v3, they have been completely separated into distinct APIs using the HTTP PUT method.
  • Request parameters: Uses the same structure as the request body parameter specification (body, type, kind, name, language_code, status) of Register subtitle (direct text input).

Delete subtitle​

  • Existing (v1): POST /media/subtitle/delete
  • Existing (v2): DELETE /vod/media-contents/{upload_file_key}/subtitles/{subtitle_id}
  • Changed (v3): DELETE /media-contents/{upload_file_key}/subtitles/{subtitle_id}
Changes
  • HTTP method conversion: The HTTP method has been changed from POST to DELETE.
Response structure details

Response structure comparison​

  • v1: { "error": 0, "message": "...", "result": true | false }
  • v2: HTTP 204 No Content
  • v3: Returns an empty data array structure { "data": [] } upon success.

Change subtitle display order​

Changes

v2 adopted a method of moving forward/backward (relative position) relative to a specific subtitle, but v3 has changed to a method of directly specifying the target position for replacement and a method of moving to the top/bottom.

Action typev2v3
Specific positionNot supportedPUT .../subtitles/{subtitle_id}/move
  • (Request body) id: Subtitle ID of the target position
Before/after a specific subtitle
  • PUT .../move-before
  • PUT .../move-after
Not supported
TopPUT .../move-firstPUT .../move-first
BottomPUT .../move-lastPUT .../move-last

Response structure specification​

Returns the detailed data object of the corresponding subtitle reflecting the changed order value (same response specification as Retrieve subtitle list).

Retrieve list of supported subtitle languages​

  • Existing (v1): GET /media/subtitle/languages
  • Existing (v2): GET /vod/languages
  • Changed (v3): GET /languages
Changes

In v3, you can filter and retrieve only languages available for subtitles by providing the use_subtitle parameter (true or false) as a query.

Response structure details

Response structure comparison​

  • v1: { "error": 0, "message": "...", "result": object }
  • v2: { "data": [{ "name": "...", "code": "..." }] }
  • v3: { "data": [ApiCommonLanguage object] } (Refer to Retrieve language list in the API reference.)