Skip to main content

Encoding Profile 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 Encoding Profile Management API v3 Reference
Feature Scope by Version
  • Not supported in v2: The encoding profile management feature is not supported in v2, so you must migrate directly from v1 to v3.
  • Common authentication: APIs in all versions use the same 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.

Common changes (v1 → v3)​

  • Response wrapper structure: The result.items array location in v1 has been standardized to a top-level data array format in v3.
  • Data type changes: The boolean property fields (is_default_preset, is_optional, is_video_ratio, is_video_vertical_flip, is_video_horizontal_flip) that were returned as integers (0 or 1) in v1 have been changed to Boolean type in v3.
  • Group information object conversion: The flat structure in v1 (media_profile_group_key, media_profile_group_name) has been changed to a nested object (group.{key, name}) structure in v3.
  • Identifier type change: The unique value identifying a profile has been changed from the integer media_profile_id to the string-based media_profile_key.

Retrieve all supported formats​

  • Previous (v1): GET /media/media_profile/profile_format
  • Changed (v3): GET /media-profiles/format
Changes

The response structure has been changed to a standard object array structure ({ "data": [{...}] }). The internal returned field names (video_bitrate, video_framerate, audio_bitrate, audio_samplerate) remain the same as before.

Retrieve encoding profile preset list​

Retrieves the entire catalog of selectable candidate presets, not the profiles registered to the account.

  • Previous (v1): GET /media/media_profile/preset
  • Changed (v3): GET /media-profiles/preset
Changes
  • All items in the Common changes above (wrapper, Boolean type, group structuring) apply.
  • In v3, the bitrate_mode and is_audio_file fields have been added to identify audio properties and whether the item is a file.
Response structure details

Response structure specification (object field names within the data array)​

  • Basic properties: id, key, name, is_audio_file, is_default_preset, is_optional, container_format, bitrate_mode
  • Video properties: video_codec, video_bitrate, video_width, video_height, video_framerate, video_rotate_degree, video_overlay_position, video_overlay_path, is_video_ratio, is_video_vertical_flip, is_video_horizontal_flip
  • Audio properties: audio_codec, audio_bitrate, audio_samplerate, audio_channel, audio_volume_control
  • Group information: group object (key, name)

Retrieve encoding profile group list​

  • Previous (v1): GET /media/media_profile_group/index
  • Changed (v3): GET /media-profile-groups
Response structure details

Response structure comparison​

  • v1
{ "error": 0, "result": { "count", "order", "items" } }
  • v3
{ "data": [{ "key", "name" }] }

Retrieve encoding profile list​

Unlike the preset catalog, this retrieves the list of profiles actually registered and activated on the account.

  • Previous (v1): GET /media/media_profile/index
  • Changed (v3): GET /media-profiles
Changes
  • Change in how group/category information is returned: In v1, information was provided via the media_profile_group_key and _name fields, but in v3, the associated category information is returned through an array (categories[].{key, name}) structure.
  • New returned fields: In v3, the status property indicating the profile's activation state and the categories[] array containing associated category information have been added to the response data.
Request parameter and response structure details

Request query parameters​

Both v1 and v3 support the order parameter, which sets the data sorting criteria based on id or name.

Response structure specification​

This mostly retains the v3 Retrieve encoding profile preset list response structure, with the status field and categories[] array object added at the bottom.

Retrieve encoding profile detail specification​

  • Previous (v1): Not supported (no single-item retrieval endpoint)
  • Changed (v3): GET /media-profiles/{media_profile_key}

Response structure specification​

Identical to the field composition of a single object within the Retrieve encoding profile list array.

Create a new encoding profile​

  • Previous (v1): POST /media/media_profile/create
  • Changed (v3): POST /media-profiles
Request body and response structure details

Request body​

Both v1 and v3 require the media_profile_preset_id (Integer) field name to be sent, and the structure is the same.

Response structure comparison​

  • v1: On success, only a message is returned without unique object information. There is a spelling error (sucessfully) in the response message.
{ "error": 0, "message": "Sucessfully created" }
  • v3 returns an HTTP 201 Created code along with the full created profile object (Retrieve encoding profile list spec) and the status field.

Update encoding profile detail specification​

  • Previous (v1): POST /media/media_profile/edit/{media_profile_id}
  • Changed (v3): PUT /media-profiles/{media_profile_key}
Changes
  • Method and identifier type change: The POST method (identifier: integer id) in v1 has been changed to the PUT method (identifier: string key) in v3.
  • Data type caution: In v1, most fields in the request body were treated as string type, but there was a type mismatch where the list retrieval response returned integer type. In v3, clear type constraints (Integer, String, Enum) are applied.
  • Expanded edit scope: In v1, only the name, bitrate, resolution, frame rate, and audio properties could be edited, but in v3, the feature has been expanded to allow editing of video_codec, video_ratio, container_format, bitrate_mode, and status information as well.
Request body details
FieldData typeRequiredAllowed values and constraints in v3
nameStringRequiredName of the profile to change
video_codecStringOptionalH.264, H.265, AV1 (H.265 and AV1 are allowed only for HW encoding)
video_ratioStringOptional16:9, 16:10, 4:3, 21:9, Custom, Auto (Transcoder 2.0 environment)
video_widthIntegerRequiredVideo width resolution (only even numbers allowed)
video_heightIntegerRequiredVideo height resolution (only even numbers allowed)
container_formatStringOptionalmp4, MP4
bitrate_modeStringOptionalcbr (constant bitrate), vbr (variable bitrate)
video_bitrateIntegerRequiredVideo bitrate value
video_framerateIntegerOptionalEnum (specify within the range 10–60)
audio_codecStringOptionalAAC, MP3
audio_bitrateIntegerOptionalEnum (specify within the range 48–320)
audio_samplerateIntegerOptionalEnum (specify within the range 11025–48000)
statusIntegerOptionalProfile activation status (0 inactive, 1 active)

Attach profile to category​

  • Previous (v1): Not supported
  • Changed (v3): POST /media-profiles/{media_profile_key}/categories/{category_key}/attach

Response structure specification​

On success, returns the profile detail object with the updated association (identical to the Retrieve encoding profile list response structure), along with the status field.

Detach profile from category​

  • Previous (v1): Not supported
  • Changed (v3): DELETE /media-profiles/{media_profile_key}/categories/{category_key}/detach

Response structure specification​

On success, returns the profile detail object reflecting the detachment. (The status field is not included in the response structure.)