본문으로 건너뛰기

인코딩 프로파일 관리

인코딩 프로파일 관리 API v3 레퍼런스 바로가기
버전별 기능 범위 안내
  • v2 미지원: 인코딩 프로파일 관리 기능은 v2에서 지원하지 않으므로, v1에서 v3로 직접 마이그레이션해야 합니다.
  • 공통 인증: 모든 버전의 API는 쿼리 스트링 파라미터(?access_token=)를 통한 공통 인증 방식을 사용합니다. 에러 판정 기준에 대한 공통 명세는 API v3 마이그레이션 가이드의 핵심 변경 사항 섹션을 참고하세요.

공통 변경 사항 (v1 → v3)​

  • 응답 래퍼 구조: v1의 배열 반환 위치인 result.items 구조가 v3에서 최상위 data 배열 형태로 표준화되었습니다.
  • 데이터 타입 변경: v1에서 정수(0 또는 1)로 반환되던 논리 속성 필드들(is_default_preset, is_optional, is_video_ratio, is_video_vertical_flip, is_video_horizontal_flip)이 v3에서는 Boolean 타입으로 변경되었습니다.
  • 그룹 정보 객체화: v1의 평면 구조(media_profile_group_key, media_profile_group_name)가 v3에서는 중첩 객체(group.{key, name}) 구조로 변경되었습니다.
  • 식별자 타입 변경: 프로파일을 식별하는 고유값이 정수형인 media_profile_id에서 문자열 형태의 media_profile_key로 변경되었습니다.

지원 규격 전체 조회​

  • 기존 (v1): GET /media/media_profile/profile_format
  • 변경 (v3): GET /media-profiles/format
변경 사항

응답 구조가 표준 객체 배열 구조({ "data": [{...}] })로 변경되었습니다. 내부 반환 필드명(video_bitrate, video_framerate, audio_bitrate, audio_samplerate)은 기존과 동일하게 유지됩니다.

인코딩 프로파일 프리셋 목록 조회​

계정에 등록된 프로파일이 아닌, 선택 가능한 전체 후보 프리셋 카탈로그를 조회합니다.

  • 기존 (v1): GET /media/media_profile/preset
  • 변경 (v3): GET /media-profiles/preset
변경 사항
  • 상단 공통 변경 사항 (래퍼, Boolean 타입, 그룹 구조화)이 모두 적용됩니다.
  • v3에서는 오디오 속성 및 파일 여부를 식별하기 위한 bitrate_mode, is_audio_file 필드가 추가되었습니다.
응답 구조 상세

응답 구조 명세 (data 배열 내 객체 필드명)​

  • 기본 속성: id, key, name, is_audio_file, is_default_preset, is_optional, container_format, bitrate_mode
  • 비디오 속성: 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_codec, audio_bitrate, audio_samplerate, audio_channel, audio_volume_control
  • 그룹 정보: group 객체 (key, name)

인코딩 프로파일 그룹 목록 조회​

  • 기존 (v1): GET /media/media_profile_group/index
  • 변경 (v3): GET /media-profile-groups
응답 구조 상세

응답 구조 대조​

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

인코딩 프로파일 목록 조회​

프리셋 카탈로그와 달리, 계정에 실제 등록 및 활성화된 프로파일 목록을 조회합니다.

  • 기존 (v1): GET /media/media_profile/index
  • 변경 (v3): GET /media-profiles
변경 사항
  • 그룹/카테고리 정보 반환 방식 변경: v1에서는 media_profile_group_key와 _name 필드로 정보를 제공했으나, v3에서는 배열(categories[].{key, name}) 구조를 통해 소속 카테고리 정보를 반환합니다.
  • 신규 반환 필드: v3에서는 프로파일의 활성화 상태를 나타내는 status 속성과 소속 카테고리 정보를 포함하는 categories[] 배열이 응답 데이터에 추가되었습니다.
요청 파라미터 및 응답 구조 상세

요청 쿼리 파라미터​

v1 및 v3 모두 id 또는 name 기반으로 데이터 정렬 기준을 설정하는 order 파라미터를 지원합니다.

응답 구조 명세​

v3의 인코딩 프로파일 프리셋 목록 조회 응답 구조를 대부분 유지하면서, 하단에 status 필드와 categories[] 배열 객체가 추가된 형태입니다.

인코딩 프로파일 상세 규격 조회​

  • 기존 (v1): 미지원 (단건 조회 엔드포인트 없음)
  • 변경 (v3): GET /media-profiles/{media_profile_key}

응답 구조 명세​

인코딩 프로파일 목록 조회 배열 내부의 단일 객체 필드 구성과 동일합니다.

신규 인코딩 프로파일 생성​

  • 기존 (v1): POST /media/media_profile/create
  • 변경 (v3): POST /media-profiles
요청 본문 및 응답 구조 상세

요청 본문​

v1 및 v3 모두 media_profile_preset_id (Integer) 필드명을 필수로 전송해야 하며, 구조는 동일합니다.

응답 구조 대조​

  • v1: 성공 시 고유 객체 정보 없이 메시지만 반환합니다. 응답 메시지 내 철자 오류(sucessfully)가 존재합니다.
{ "error": 0, "message": "Sucessfully created" }
  • v3는 HTTP 201 Created 코드와 함께 생성된 전체 프로파일 객체(인코딩 프로파일 목록 조회 스펙)와 status 필드를 반환합니다.

인코딩 프로파일 상세 규격 수정​

  • 기존 (v1): POST /media/media_profile/edit/{media_profile_id}
  • 변경 (v3): PUT /media-profiles/{media_profile_key}
변경 사항
  • 메서드 및 식별자 타입 변경: v1의 POST 메서드(식별자: 정수 id)가 v3에서 PUT 메서드(식별자: 문자열 key)로 변경되었습니다.
  • 데이터 타입 주의: v1은 요청 본문의 필드가 대부분 문자형으로 처리되었으나, 목록 조회 응답은 정수형으로 반환되는 타입 불일치 현상이 있었습니다. v3에서는 명확한 타입(Integer, String, Enum) 제약이 적용됩니다.
  • 수정 허용 범위 확장: v1에서는 이름, 비트레이트, 해상도, 프레임레이트, 오디오 속성 정도만 수정할 수 있었으나, v3에서는 video_codec, video_ratio, container_format, bitrate_mode, status 정보까지 수정할 수 있도록 기능이 확장되었습니다.
요청 본문 상세
필드데이터 타입필수 여부v3 허용값 및 제약 조건
nameString필수변경할 프로파일 명칭
video_codecString선택H.264, H.265, AV1 (단, H.265, AV1은 HW 인코딩 시에만 허용)
video_ratioString선택16:9, 16:10, 4:3, 21:9, Custom, Auto (트랜스코더 2.0 환경)
video_widthInteger필수비디오 폭 해상도 (짝수만 허용)
video_heightInteger필수비디오 높이 해상도 (짝수만 허용)
container_formatString선택mp4, MP4
bitrate_modeString선택cbr (고정 비트레이트), vbr (가변 비트레이트)
video_bitrateInteger필수비디오 비트레이트 값
video_framerateInteger선택Enum (10 ~ 60 범위 내 지정)
audio_codecString선택AAC, MP3
audio_bitrateInteger선택Enum (48 ~ 320 범위 내 지정)
audio_samplerateInteger선택Enum (11025 ~ 48000 범위 내 지정)
statusInteger선택프로파일 활성화 상태 (0 비활성, 1 활성)

프로파일–카테고리 연결​

  • 기존 (v1): 미지원
  • 변경 (v3): POST /media-profiles/{media_profile_key}/categories/{category_key}/attach

응답 구조 명세​

성공 시 status 상태 필드와 함께 연결이 갱신된 프로파일 상세 객체(인코딩 프로파일 목록 조회 응답 구조와 동일)를 반환합니다.

프로파일–카테고리 연결 해제​

  • 기존 (v1): 미지원
  • 변경 (v3): DELETE /media-profiles/{media_profile_key}/categories/{category_key}/detach

응답 구조 명세​

성공 시 연결 해제가 반영된 프로파일 상세 객체를 반환합니다. (응답 구조 내에 status 필드는 포함되지 않습니다.)