Skip to main content

Transcoding 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 Transcoding Management API v3 Reference
Feature scope by version
  • v2 not supported: The transcoding management feature is not supported in v2, so you must migrate directly from v1 to v3.
  • Common authentication: APIs of all versions use the common authentication method via a query string parameter (?access_token=). For error handling guidance, refer to the Core Changes section.

Get transcoding progress status​

  • Previous (v1 - list retrieval): GET /media/upload_file
  • Previous (v1 - single item retrieval): GET /media/media_content/view/{media_content_id}
  • Previous (v2): Not supported
  • Changed (v3): GET /media-contents/{upload_file_key}/progress
Changes
  • Endpoint unification: In v1, the list retrieval and single item retrieval endpoints were separate, but in v3, they have been unified into a single retrieval endpoint based on the unique identifier upload_file_key.
  • Identifier parameter caution: The v1 single item retrieval API used watcher_file_key as a parameter, but v3 uses upload_file_key, the unique identifier of the upload file. Pay close attention to this mapping when migrating.
Transcoding status code and response structure details

Transcoding status codes (transcoding_stage)​

The status codes remain the same in v1 and v3. Status code 11 (preparing for transcoding) passes through the 0 (waiting) or 12 (in progress) state in the internal job loop before immediately transitioning to the 21 (completed) state.

Status codeDescription
0Waiting
11Preparing for transcoding
1Transcoding started
12Transcoding in progress
21Transcoding completed
51Transcoding error
52Initialization failed

Response structure comparison​

  • v1 (single item retrieval)
{
  "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
  }
}

Create additional transcoding job​

Manually schedules an additional transcoding job with a different quality/format (Profile) for a specific media content.

  • Previous (v1): POST /media/library/create_transcoding_file/{upload_file_key} (profile_key included in the request body)
  • Previous (v2): Not supported
  • Changed (v3): POST /media-contents/{upload_file_key}/media-profiles/{media_profile_key}/transcoding-jobs
Changes
  • Parameter location moved: The target profile key (profile_key), which was included in the request body in v1, has been changed to a URL path parameter (media_profile_key) in v3.
  • Restriction (unchanged): File profiles that are already in progress or completed are excluded from additional transcoding targets. This business logic is the same in v1 and v3.

Response structure comparison​

  • v1: { error, message } (does not provide the created job identifier)
  • v3: { "data": [{ "key": "new_job_key" }], "status": "ok" } (returns an array of newly created transcoding job identifiers)

Manage transcoding files (New in v3)​

  • Previous (v1/v2): Not supported
  • Changed (v3): New endpoints provided

List of new API endpoints​

Transcoding files can be manipulated through two identification schemes: the file ID (transcoding_file_id) and the encoding profile key (profile_key).

FeatureHTTPv3 endpoint
Get list of transcoding filesGET/media-contents/{upload_file_key}/transcoding-files
Generate transcoding file download URLGET/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/download
Enable transcoding file (by file ID)PUT/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/enable
Enable transcoding file (by profile key)PUT/media-contents/{upload_file_key}/media-profiles/{profile_key}/enable
Disable transcoding file (by file ID)PUT/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}/disable
Disable transcoding file (by profile key)PUT/media-contents/{upload_file_key}/media-profiles/{profile_key}/disable
Delete transcoding file (by file ID)DELETE/media-contents/{upload_file_key}/transcoding-files/{transcoding_file_id}
Delete transcoding file (by profile key)DELETE/media-contents/{upload_file_key}/media-profiles/{profile_key}
Response structure details

Response specification for transcoding file list retrieval/enable/disable​

{
  "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"
    }
  ]
}

Response specification for generating transcoding file download URL​

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

Response specification for deleting transcoding file​

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