콘텐츠

버전별 기능 범위 안내

공통 인증: 모든 버전의 API는 쿼리 스트링 파라미터(?access_token=)를 통한 공통 인증 방식을 사용합니다. 에러 판정 기준에 대한 공통 명세는 API v3 마이그레이션 가이드의 핵심 변경사항 섹션을 참고하세요.
트랜스코딩: 트랜스코딩 진행 상태 조회 및 트랜스코딩 파일에 관한 명세는 트랜스코딩 관리 문서를 참고하세요.

콘텐츠 관리 API v3 레퍼런스 바로가기

전체 콘텐츠 목록 조회

기존 (v1): GET /media/library/media_content
기존 (v2): 미지원 (채널별 콘텐츠 목록 조회만 지원)
변경 (v3): GET /media-contents

변경사항

응답 내 데이터 구조 변경: 응답 객체의 배열 반환 위치가 기존 result.item[]에서 data[]로 표준화되었으며, 페이징 처리를 위해 pagination 객체가 추가되었습니다.
배열 항목 필드: 배열 내 개별 콘텐츠 아이템의 상세 필드 규격은 하단의 '콘텐츠 정보 조회'와 동일합니다.

채널별 콘텐츠 목록 조회

채널 관리 문서의 채널별 콘텐츠 목록 조회 섹션을 참고하세요.

카테고리별 콘텐츠 목록 조회

기존 (v1/v2): 미지원
변경 (v3): GET /categories/{category_key}/media-contents

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

요청 파라미터

요청 파라미터 규격은 전체 콘텐츠 목록 조회 API 구성과 완전히 일치합니다.

응답 구조 명세

{
  "status": 200,
  "data": [
    {
      "title": "string",
      "upload_file_key": "string"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 100
  }
}

콘텐츠 업로드 URL 생성

기존 (v1): POST /media_auth/upload/create_url
기존 (v2): 미지원
변경 (v3): POST /upload/create-url

변경사항

업로드 처리 호스트: 발급된 upload_url은 공통 도메인 주소가 아닌 업로드 전용 도메인인 https://upload.kr.kollus.com을 타깃으로 반환됩니다.
필드명 변경: v1의 will_be_expired_at 필드가 v3에서 expired_at으로 변경되었습니다.

요청 본문 및 응답 구조 상세

요청 본문

필드	데이터 타입	필수 여부	설명
`expire_time`	`Integer`	선택	업로드 URL 유효 시간 (기본값: 600초, 최댓값: 21600초)
`title`	`String`	필수	콘텐츠 제목
`category_key`	`String`	선택	분류 대상 카테고리 고유 식별값
`is_encryption_upload`	`Integer`	선택	암호화 설정 (`0`: 비암호화(일반) 콘텐츠, `1`: 암호화 콘텐츠)
`is_audio_upload`	`Integer`	선택	오디오 전용 콘텐츠 설정 (`0`: 비디오 포함, `1`: 오디오 전용)
`use_ai_script`	`Integer`	선택	AI배속 적용 여부
`use_ai_subtitle`	`Integer`	선택	AI자막 생성 여부
`use_ai_outline`	`Integer`	선택	AI요약·챕터 생성 여부
`ai_subtitle_language`	`String`	선택	AI자막 언어 설정 (영상 또는 오디오의 주요 사용 언어)
`ai_subtitle_status`	`Integer`	선택	AI자막 공개 설정 (`0`: 비공개, `1`: 공개)
`ai_subtitle_kind`	`Integer`	선택	AI자막 유형 설정 (`0`: 메인 자막, `1`: 서브 자막)

응답 구조 대조

v1

{
  "error": 0,
  "message": "success",
  "result": {
    "upload_url": "https://upload.kr.kollus.com/old-upload-path",
    "progress_url": "https://upload.kr.kollus.com/old-progress-path",
    "upload_file_key": "v1_file_key",
    "will_be_expired_at": 1672531199
  }
}

v3

{
  "status": 201,
  "data": {
    "upload_url": "https://upload.kr.kollus.com/v3-upload-path",
    "progress_url": "https://upload.kr.kollus.com/v3-progress-path",
    "upload_file_key": "v3_file_key",
    "expired_at": 1672531199
  }
}

콘텐츠 정보 조회

기존 (v1): GET /media/library/media_content/{upload_file_key}
기존 (v2): GET /vod/media-contents/{upload_file_key}
변경 (v3): GET /media-contents/{upload_file_key}

변경사항

v1 → v3 변환: 전반적인 평면 구조와 필드명은 유지되나, 데이터 타입이 대거 변경되었습니다. (예: Integer에서 Boolean으로의 변환, Unix Timestamp에서 ISO8601 문자열로 타입 변경)
v2 → v3 변환: v2에서 여러 계층으로 중첩되어 있던 하위 객체(kind, category, original_file) 구조들이 v3에서 직관적인 평면 구조로 변경되었습니다.
v1 전용 필드 제거: 기존 v1 응답에 포함되던 transcoding_files, channels, metadata 필드는 v3에서 완전히 제거되었습니다.

응답 필드 상세 매핑

필드	v1 규격	v2 규격	v3 규격	마이그레이션 참고사항
`kind`	Integer + `kind_name`	`kind.{type, value}` 객체	Integer + `kind_name`	v2 구조만 중첩 객체 타입으로 반환됨
`duration`	String	Integer (단위: 초)	String (HH:MM:SS)	v3는 타임코드 포맷 사용
`category`	`category_name` / `_key` (평면)	`category.{id, key, name, level_path}` (중첩)	`category_name` / `_key` (평면)	v3는 v1과 동일한 평면 구조로 반환
`original_file`	`original_file_name` / `_size` (평면)	`original_file.{name, size}` (중첩)	평면 구조 반환	파일 크기 포맷: String (v1) → Integer (v2/v3)
`use_encryption`	Integer (0 또는 1)	Boolean	Boolean	v1 대비 정수형 변수가 Boolean 타입으로 수정됨
`status`	Integer (예: 1)	Boolean	Boolean	v1 대비 정수형 변수가 Boolean 타입으로 수정됨
`transcoded_at`, `created_at`, `updated_at`	Unix Integer	ISO8601 문자열	ISO8601 문자열	-
*`vr_`**	미지원	`vr_information.{type, value}`	`vr_info.{projection_type, stereo_mode}`	v2 대비 v3에서 키 이름이 변경됨
`human_readable_original_file_size`	제공	미지원	제공	데이터 가독성을 고려한 크기 변환 값 (예: "823.5MB")
`media_information`	3분류 (file, video, audio)	2분류 (audio 누락)	3분류 (file, video, audio)	v3는 v1과 동일하게 3분류 정보 완전 제공
`transcoding_stage`	제공	미지원	제공	상세 코드 명세는 트랜스코딩 관리 문서 참고
`transcoding_stage_name`	제공	미지원	제공	상세 코드 명세는 트랜스코딩 관리 문서 참고
`poster_url`, `snapshot_url`	제공	미지원	제공	대표 이미지 주소 정보 필드 추가
`is_passthrough`	-	-	Boolean	v3에 추가된 콘텐츠 상태/매핑 필드
`media_content_keys[]`	-	-	Array	v3에 추가된 콘텐츠 상태/매핑 필드

콘텐츠 정보 수정

기존 (v1): POST /media/media_content/update
기존 (v2): PUT /vod/media-contents/{upload_file_key}
변경 (v3): PUT /media-contents/{upload_file_key}

변경사항

대상 식별 방식: v1은 요청 본문 내의 고유 식별용 정수 id로 대상을 지정했으나, v3는 URL 경로의 {upload_file_key}를 통해 식별합니다.
VR 설정 구조화: v2에서는 평면 파라미터(projection_type, stereo_mode)로 전송했으나, v3에서는 vr 상위 객체 하위의 필드(vr.projection_type, vr.stereo_mode)로 묶어서 전송해야 합니다.

요청 본문 및 응답 구조 상세

요청 본문

v1: id(필수)+title
v2: title, projection_type(rectangular/equirectangular), stereo_mode(mono)
v3: title, vr.projection_type, vr.stereo_mode

응답 구조 대조

v1: { error, message }
v2: { data: ApiVodMediaContent }
v3: { "data": ApiVodMediaContent, "status": "ok" }

콘텐츠 메타데이터 조회

기존 (v1): GET /media/library/get_metadata/{upload_file_key}
기존 (v2): 미지원
변경 (v3): 미지원

메타데이터 서비스 폐기

v3에서는 메타데이터 전용 조회 엔드포인트가 제공되지 않으며, 콘텐츠 정보 조회 응답 내부의 metadata 세부 필드까지 일관되게 폐기되었습니다.

콘텐츠 메타데이터 수정

기존 (v1): POST /media/library/update_metadata/{upload_file_key}
기존 (v2): 미지원
변경 (v3): 미지원

메타데이터 서비스 폐기

상기 메타데이터 조회용 API의 폐기 정책에 따라 메타데이터 정보 수정 기능 역시 v3에서 폐기되었습니다.

콘텐츠 삭제

기존 (v1/v2): 미지원 (콘텐츠의 물리적 삭제 기능이 존재하지 않아, 활성/비활성 제어를 통해서만 라이프사이클을 관리하였습니다.)
변경 (v3): DELETE /media-contents/{upload_file_key}

응답 구조 상세

응답 구조 명세

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

콘텐츠 카테고리 변경

기존 (v1): POST /media/library/change_category/{upload_file_key} (본문에 category_key 포함)
기존 (v2): 미지원
변경 (v3): PUT /media-contents/{upload_file_key}/categories/{category_key}

변경사항

HTTP 메서드 전환: HTTP 메서드가 POST에서 PUT으로 변경되었습니다.
파라미터 위치 이동: v1에서 요청 본문에 담아 보내던 category_key가 v3에서는 경로 파라미터로 통합되었습니다.

응답 구조 상세

v1: { error, message } (별도의 결과값 데이터 없음)
v3: { "data": ApiVodMediaContentCategory, "status": "ok" } (신규 카테고리가 매핑된 결과 정보 반환)

콘텐츠 비활성화

기존 (v1): POST /media/library/set_disable/{upload_file_key}
기존 (v2): 미지원
변경 (v3): PUT /media-contents/{upload_file_key}/disable

변경사항

HTTP 메서드 전환: HTTP 메서드가 POST에서 PUT으로 변경되었습니다.
응답 표준화: ApiVodMediaContentStatus 객체 구조로 반환됩니다.

콘텐츠 활성화

기존 (v1): POST /media/library/set_enable/{upload_file_key}
기존 (v2): 미지원
변경 (v3): PUT /media-contents/{upload_file_key}/enable

변경사항

HTTP 메서드 전환: HTTP 메서드가 POST에서 PUT으로 변경되었습니다.
응답 표준화: { "data": ApiVodMediaContentStatus, "status": "ok" }으로 반환됩니다.

포스터 이미지 업로드

기존 (v1): POST /media/library/upload_poster/{upload_file_key}
기존 (v2): 미지원
변경 (v3): POST /media-contents/{upload_file_key}/poster

변경사항

필수 필드: v3부터 multipart/form-data 헤더 포맷을 사용하여 요청 본문에 file 필드(Binary 데이터, 필수)를 전달해야 합니다.
응답 구조: v1의 결과 메시지 반환 방식에서 v3의 규격화된 포맷({ "data": [], "status": "ok" })으로 대체됩니다.

포스터 이미지 다운로드

기존 (v1/v2): 미지원
변경 (v3): GET /media-contents/{upload_file_key}/poster/download

응답 구조 상세

응답 구조 명세

{
  "data": {
    "expires": "2026-07-01T09:12:08+00:00",
    "download_url": "https://download.kr.kollus.com/path-to-poster-file"
  }
}

원본 파일 다운로드

기존 (v1): 미지원
기존 (v2): GET /vod/media-contents/{upload_file_key}/original/download
변경 (v3): GET /media-contents/{upload_file_key}/original-file/download

변경사항

경로명 변경: 기존의 original로 선언되던 경로명이 original-file로 변경되었습니다.
필드 정보 치환: v2 응답 객체 속의 다운로드 URI 필드명인 download_uri가 v3에서 download_url로 일괄 수정되었습니다.

응답 구조 명세

{
  "data": {
    "expires": "2026-07-01T09:12:08+00:00",
    "download_url": "https://download.kr.kollus.com/path-to-original-file"
  }
}

스냅샷 이미지 생성 (v2 전용)

기존 (v1): 미지원
기존 (v2): POST /vod/media-contents/{upload_file_key}/snapshot
변경 (v3): 미지원

스냅샷 실시간 추출 기능 폐기

사용자가 타임코드 시점을 직접 커스텀하여 섬네일 이미지를 즉시 재생성하던 v2 스크립트 기능은 v3에서 완전히 폐기되었습니다. v3에서는 미디어 업로드 처리 시 초기 시스템 스케줄러가 자동 생성하는 고정 스냅샷 정보(snapshot_url)만 조회할 수 있습니다.

스냅샷 이미지 다운로드 (v2 전용)

기존 (v1): 미지원
기존 (v2): POST /vod/media-contents/get-snapshot-download-link (본문에 path 포함)
변경 (v3): 미지원

스냅샷 실시간 추출 기능 폐기

스냅샷 이미지 생성 기능 폐기에 따라 스냅샷 이미지 다운로드 API 역시 v3에서 제공되지 않습니다.

전체 콘텐츠 목록 조회​

채널별 콘텐츠 목록 조회​

카테고리별 콘텐츠 목록 조회​

요청 파라미터​

응답 구조 명세​

콘텐츠 업로드 URL 생성​

요청 본문​

응답 구조 대조​

v1​

v3​

콘텐츠 정보 조회​

콘텐츠 정보 수정​

요청 본문​

응답 구조 대조​

콘텐츠 메타데이터 조회​

콘텐츠 메타데이터 수정​

콘텐츠 삭제​

응답 구조 명세​

콘텐츠 카테고리 변경​

콘텐츠 비활성화​

콘텐츠 활성화​

포스터 이미지 업로드​

포스터 이미지 다운로드​

응답 구조 명세​

원본 파일 다운로드​

응답 구조 명세​

스냅샷 이미지 생성 (v2 전용)​

스냅샷 이미지 다운로드 (v2 전용)​

전체 콘텐츠 목록 조회

채널별 콘텐츠 목록 조회

카테고리별 콘텐츠 목록 조회

요청 파라미터

응답 구조 명세

콘텐츠 업로드 URL 생성

요청 본문

응답 구조 대조

v1

v3

콘텐츠 정보 조회

콘텐츠 정보 수정

요청 본문

응답 구조 대조

콘텐츠 메타데이터 조회

콘텐츠 메타데이터 수정

콘텐츠 삭제

응답 구조 명세

콘텐츠 카테고리 변경

콘텐츠 비활성화

콘텐츠 활성화

포스터 이미지 업로드

포스터 이미지 다운로드

응답 구조 명세

원본 파일 다운로드

응답 구조 명세

스냅샷 이미지 생성 (v2 전용)

스냅샷 이미지 다운로드 (v2 전용)