채널 관리

채널 관리 API v3 레퍼런스 바로가기

버전별 기능 범위 안내

v3 신규 기능: 콜백 URL 설정, 보안 기능 설정, 레퍼러 기반 접근 제어, 플레이어 스킨 연결 등의 채널별 독립 설정 엔드포인트는 v3에 신규 추가된 기능입니다.
공통 인증: 모든 버전의 API는 쿼리 스트링 파라미터(?access_token=)를 통한 공통 인증 방식을 사용합니다. 에러 판정 기준에 대한 공통 명세는 API v3 마이그레이션 가이드의 핵심 변경 사항 섹션을 참고하세요.

채널 목록 조회

기존 (v1): GET /media/channel/index
변경 (v3): GET /channels

변경 사항

응답 데이터 구조 변경: 반환되는 데이터의 배열 위치가 기존 result.items[]에서 data[] 구조로 변경되었으며, 페이징 처리를 위한 pagination 객체가 추가되었습니다.
필터 및 페이지네이션 파라미터 추가: v1에서는 order 파라미터만 지원했으나, v3에서는 kind, status, page, per_page 파라미터가 추가되었습니다.

요청 파라미터 및 응답 필드 상세 매핑

요청 쿼리 파라미터

파라미터	v1 지원 여부	v3 지원 여부	설명
`order`	지원 (`created_at`/`position`과 `asc`/`desc` 조합, 기본값: `position_asc`)	지원 (v1과 동일한 Enum 스펙 유지)	정렬 기준
`kind`	미지원	지원	채널 종류 필터링
`status`	미지원	지원	채널 활성화 상태 필터링 (`0`: 비활성, `1`: 활성)
`page`	미지원	지원	조회 대상 페이지 번호
`per_page`	미지원	지원	페이지당 출력 데이터 개수

응답 필드 매핑

key, name, position 필드는 전 버전 공통으로 동일하게 유지됩니다.

필드	v1 구조 (`result.items[]`)	v3 구조 (`data[]`, `ApiVodChannel` 객체)	참고
콘텐츠 카운트	`count_of_media_contents`	`count_of_contents`	명칭 단순화
활성 상태	`status` (정수형, `1`인 경우 활성)	`status` (Boolean)	데이터 타입 변경
채널 종류	응답 최상위 속성으로 반환	응답 본문에서 분리	-
신규 추가 필드	-	`description`, 콜백 및 보안 관련 설정 필드(`use_pingback`, `pingback_url` 등)	부가 필드 추가

채널 객체 명세

v3 응답 스펙의 ApiVodChannel 객체는 아래와 같은 구조를 가집니다.

{
  "key": "string",
  "name": "string",
  "description": "string",
  "use_pingback": true,
  "pingback_url": "string",
  "leave_pingback_url": "string",
  "play_callback_url": "string",
  "use_referer_check": 0,
  "referer_check_domains": "string",
  "referer_reject_domains": "string",
  "referer_empty_allow": true,
  "use_pc_download": true,
  "pc_download_callback_url": "string",
  "use_mobile_download": true,
  "mobile_download_callback_url": "string",
  "default": true,
  "is_shared": true,
  "is_encrypted": true,
  "disable_tvout": true,
  "count_of_contents": 0,
  "position": 0,
  "status": true,
  "created_at": "string",
  "updated_at": "string"
}

신규 채널 생성

기존 (v1): POST /media/channel/create
변경 (v3): POST /channels

변경 사항

설정 필드 분리: v1 생성 API에 존재하던 핑백(Pingback) 및 재생 제어 관련 필드가 v3 생성 스펙에서 제거되었습니다. v3에서는 채널 생성 완료 후 별도의 콜백 엔드포인트를 통해 설정해야 합니다.
미지원 필드 전환: v1의 media_player_policy 및 progress_plugin 필드는 v3에서 대체 필드 없이 제거되었습니다.
응답 데이터 명세 고도화: v1에서는 성공 시 생성된 고유 키 정보(result.key)만 반환했으나, v3에서는 HTTP 201 Created 상태 코드와 함께 새로 생성된 채널 객체 전체를 반환합니다.

요청 본문 및 응답 구조 상세

요청 본문

필드	데이터 타입 (v1)	데이터 타입 (v3)	필수 여부	설명
`name`	String	String	필수	생성할 채널 이름 (최대 50자)
`is_shared`	Integer	Integer	선택	채널 공유 정책 설정 (`0`(기본값): 비공유 채널, `1`: 공유 채널)
`is_encrypted`	Integer	Integer	선택	채널 보안 정책 설정 (`0`(기본값): 일반 채널, `1`: 암호화 콘텐츠 전용 채널)
`use_pingback`	Integer	-	-	v3 전용 콜백 엔드포인트로 기능 이관
`pingback_url`	String	-	-	v3 전용 콜백 엔드포인트로 기능 이관
`media_player_policy`	String	-	-	v3에서 필드 제거
`progress_plugin`	Integer	-	-	v3에서 필드 제거
`description`	-	String	선택	채널 설명 (v3 신규 추가)

응답 구조 대조

v1: 성공 시 고유 키 형태만 반환되며, 응답 메시지 내 철자 오류(sucessfully)가 존재합니다.

{ "error": 0, "message": "sucessfully", "result": { "key": "key_string" } }

v3: 표준 데이터 구조를 반환합니다.

{ "data": ApiVodChannel object, "status": "ok" }

채널 정보 조회

기존 (v1/v2): 미지원 (단건 조회 엔드포인트 없음)
변경 (v3): GET /channels/{channel_key}

응답 구조 상세

응답 구조 명세

응답 필드는 채널 목록 조회 스펙과 동일합니다.

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

채널 정보 수정

기존 (v1/v2): 미지원
변경 (v3): PUT /channels/{channel_key}

요청 본문 및 응답 구조 상세

요청 본문

필드	데이터 타입	필수 여부	설명
`name`	String	필수	채널 이름
`description`	String	선택	채널 설명
`use_realtime`	Integer	선택	실시간 스트리밍(HLS) 사용 여부 (`0`: 미사용, `1`: 사용)
`use_aes128`	Integer	선택	AES-128 암호화 사용 여부 (`0`: 미사용, `1`: 사용)

응답 구조 명세

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

채널 삭제

기존 (v1): POST /media/channel/delete/{channel_key}
변경 (v3): DELETE /channels/{channel_key}

변경 사항

HTTP 메서드 전환: HTTP 메서드가 POST에서 DELETE로 변경되었습니다.
응답 구조 단순화: 기존 성공 반환 규격을 간소화하여, 삭제 처리가 승인되었음을 뜻하는 빈 배열 구조("data": [])를 반환합니다.

채널별 콘텐츠 목록 조회

기존 (v1): GET /media/channel/media_content
기존 (v2): GET /vod/channels/{media_package}/media-contents
변경 (v3): GET /channels/{channel_key}/media-contents

변경 사항

경로 파라미터 전환: 채널 식별자 전달 방식이 v1의 쿼리 스트링 구조에서 URL 경로 파라미터 구조로 표준화되었습니다. v2는 경로 파라미터명으로 media_package를 사용했으나, v3는 channel_key로 통일했습니다.
필터 파라미터 추가: v3에서는 정렬 및 페이징 처리를 비롯하여 검색 및 상태 필터 등 풍부한 조건부 쿼리 파라미터들이 추가되었습니다.

요청 파라미터 및 응답 구조 상세

요청 쿼리 파라미터

order, page, per_page: 조회 정렬 방식 및 페이징 제어
keyword, state, encryption, publish, content_type: 상태값 및 유형 필터
exist_original, exist_subtitle: 원본 파일 및 자막 존재 여부 필터
start_date, end_date: 기간 범위 검색 필터

응답 구조 대조

{ "error": 0, "result": { "count": 10, "order": "position_asc", "per_page": 20, "items": { "item": [] } } }

{ "data": [{ "transcoding_files": [], "subtitles": [] }] }

{ "data": [ApiVodMediaContent object], "pagination": { "current_page": 1, "per_page": 10, "total": 100 } }

채널 내 콘텐츠 단건 조회

기존 (v1): GET /media/channel/media_content/{upload_file_key}
변경 (v3): 미지원 (하단 API 통합 안내 참고)

API 통합 안내

v3에서는 채널 내 콘텐츠 단건 조회 API가 폐기되었습니다. 대신 동일한 데이터 범위 조회를 보장하는 범용 콘텐츠 관리 단건 조회 기능인 GET /media-contents/{upload_file_key} 형태로 통합되었습니다.

채널–콘텐츠 연결

기존 (v1): POST /media/channel/attach/{upload_file_key}
변경 (v3): POST /channels/{channel_key}/media-contents/{upload_file_key}/attach

식별자 파라미터 매핑 주의

v1에서는 콘텐츠 식별자(upload_file_key)만 주소 경로에 포함하고 대상 채널 키(channel_key)는 요청 본문에 담아 전송했습니다. 하지만 v3에서는 두 식별자가 모두 URL 경로 파라미터에 순서대로 배치됩니다.

v1의 구현 형태를 바탕으로 URL 엔드포인트 주소만 기계적으로 치환할 경우, 경로 상의 채널 키와 콘텐츠 키 정보가 서로 엇갈려 잘못 매핑되면서 의도와 다르게 연결되거나 연결에 실패(404 Not Found)할 수 있으므로 파라미터 바인딩 순서를 반드시 검증해야 합니다.

요청 파라미터 전송 위치 및 응답 구조 상세

요청 파라미터 전송 위치 대조

구분	v1	v3
`channel_key`	요청 본문	URL 경로 파라미터 (앞부분 배치)
`upload_file_key`	URL 경로 파라미터	URL 경로 파라미터 (뒷부분 배치)

응답 구조 대조

{ "error": 0, "message": "...", "result": { "media_content_key": "..." } }

{ "data": ApiVodMediaContentKey object, "status": "ok" }

채널–콘텐츠 연결 해제

기존 (v1): POST /media/channel/detach/{upload_file_key}
변경 (v3): DELETE /channels/{channel_key}/media-contents/{upload_file_key}/detach

변경 사항

HTTP 메서드 전환: HTTP 메서드가 POST에서 DELETE로 변경되었습니다.
파라미터 위치 변경: 채널 키(channel_key) 항목이 기존 요청 본문 구조에서 URL 경로 파라미터로 변경되어 포함됩니다.
응답 데이터 정형화: 성공 시 텍스트 응답값 대신 빈 배열 구조("data": [])를 반환합니다.

채널–플레이어 스킨 연결

기존 (v1/v2): 미지원
변경 (v3): POST /channels/{channel_key}/player-skins/{skin_id}/attach

응답 구조 상세

응답 구조 명세

{ 
  "data": ApiVodPlayerSkin object, 
  "status": "ok" 
}

채널–플레이어 스킨 연결 해제

기존 (v1/v2): 미지원
변경 (v3): DELETE /channels/{channel_key}/player-skins

응답 구조 상세

응답 구조 명세

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

콜백 URL 설정 - 콘텐츠 추가/삭제/재생

기존 (v1/v2): 미지원
변경 (v3): PUT /channels/{channel_key}/callback

신규 기능 안내

기존 v1 생성 API의 속성으로 일괄 처리되던 핑백 및 재생 제어 관련 설정 구조가 독립된 API로 분리되었습니다.

요청 본문 및 응답 구조 상세

요청 본문

필드	데이터 타입	필수 여부	설명
`use_pingback`	Integer	필수	콜백 기능 활성화 (`0`: 비활성화, `1`: 활성화)
`pingback_url`	String	선택	콘텐츠의 채널 추가 콜백 URL
`leave_pingback_url`	String	선택	콘텐츠의 채널 삭제 콜백 URL
`play_callback_url`	String	선택	재생 콜백 URL

응답 구조 명세

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

콜백 URL 설정 - 다운로드

기존 (v1/v2): 미지원
변경 (v3): PUT /channels/{channel_key}/download-callback

요청 본문 및 응답 구조 상세

요청 본문

필드	데이터 타입	필수 여부	설명
`use_pc_download`	Integer	필수	PC 다운로드 기능 활성화 (`0`: 비활성화, `1`: 활성화)
`pc_download_callback_url`	String	선택	PC 다운로드 콜백 URL
`use_mobile_download`	Integer	필수	모바일 다운로드 기능 활성화 (`0`: 비활성화, `1`: 활성화)
`mobile_download_callback_url`	String	선택	모바일 다운로드 콜백 URL

응답 구조 명세

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

외부 디스플레이 출력 차단

기존 (v1/v2): 미지원
변경 (v3): PUT /channels/{channel_key}/security

요청 본문 및 응답 구조 상세

요청 본문

필드	데이터 타입	필수 여부	설명
`disable_tvout`	Integer	필수	외부 디스플레이 출력 차단 설정 (`0`: 미차단, `1`: 차단)

응답 구조 명세

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

레퍼러 기반 접근 제어

기존 (v1/v2): 미지원
변경 (v3): PUT /channels/{channel_key}/referer

요청 본문 및 응답 구조 상세

요청 본문

필드	데이터 타입	필수 여부	설명
`use_referer_check`	Integer	필수	레퍼러 접근 제어 정책 설정 (`1`: 특정 도메인 허용, `2`: 특정 도메인 차단)
`referer_check_domains[]`	Array	선택	재생을 허용할 도메인 주소 목록
`referer_reject_domains[]`	Array	선택	재생을 차단할 도메인 주소 목록
`referer_empty_allow`	Boolean	선택	레퍼러 정보가 없는 요청 차단 여부

응답 구조 명세

{ 
  "data": ApiVodChannel object, 
  "status": "ok" 
}

채널 목록 조회​

요청 쿼리 파라미터​

응답 필드 매핑​

채널 객체 명세​

신규 채널 생성​

요청 본문​

응답 구조 대조​

채널 정보 조회​

응답 구조 명세​

채널 정보 수정​

요청 본문​

응답 구조 명세​

채널 삭제​

채널별 콘텐츠 목록 조회​

요청 쿼리 파라미터​

응답 구조 대조​

채널 내 콘텐츠 단건 조회​

채널–콘텐츠 연결​

요청 파라미터 전송 위치 대조​

응답 구조 대조​

채널–콘텐츠 연결 해제​

채널–플레이어 스킨 연결​

응답 구조 명세​

채널–플레이어 스킨 연결 해제​

응답 구조 명세​

콜백 URL 설정 - 콘텐츠 추가/삭제/재생​

요청 본문​

응답 구조 명세​

콜백 URL 설정 - 다운로드​

요청 본문​

응답 구조 명세​

외부 디스플레이 출력 차단​

요청 본문​

응답 구조 명세​

레퍼러 기반 접근 제어​

요청 본문​

응답 구조 명세​

채널 목록 조회

요청 쿼리 파라미터

응답 필드 매핑

채널 객체 명세

신규 채널 생성

요청 본문

응답 구조 대조

채널 정보 조회

응답 구조 명세

채널 정보 수정

요청 본문

응답 구조 명세

채널 삭제

채널별 콘텐츠 목록 조회

요청 쿼리 파라미터

응답 구조 대조

채널 내 콘텐츠 단건 조회

채널–콘텐츠 연결

요청 파라미터 전송 위치 대조

응답 구조 대조

채널–콘텐츠 연결 해제

채널–플레이어 스킨 연결

응답 구조 명세

채널–플레이어 스킨 연결 해제

응답 구조 명세

콜백 URL 설정 - 콘텐츠 추가/삭제/재생

요청 본문

응답 구조 명세

콜백 URL 설정 - 다운로드

요청 본문

응답 구조 명세

외부 디스플레이 출력 차단

요청 본문

응답 구조 명세

레퍼러 기반 접근 제어

요청 본문

응답 구조 명세