본문으로 건너뛰기

Kollus VOD API v3 마이그레이션 가이드

Kollus VOD API v1, v2 서비스를 사용 중인 고객사가 v3로 안정적으로 전환하기 위한 핵심 변경 사항 및 엔드포인트 매핑 정보를 안내합니다. 아래의 5가지 핵심 변경 사항을 먼저 확인한 후, 기능별 엔드포인트 인덱스를 통해 각 기능별 상세 매핑 페이지로 이동하여 작업을 진행하세요.

서비스 종료 안내

Kollus VOD API v1, v2는 2026년 12월 31일부로 지원이 전면 종료됩니다. 원활한 서비스 유지를 위해 기한 내에 v3로 마이그레이션을 완료해 주시기 바랍니다.

핵심 변경 사항​

모든 엔드포인트에 공통으로 적용되는 가장 중요한 변경 사항입니다. 마이그레이션 코드 설계 시 가장 먼저 반영해야 합니다.

1. Base URL 변경​

업로드 엔드포인트를 제외한 모든 API의 호스트 도메인이 변경됩니다.

  • 기존 (v1): api.kr.kollus.com/0
  • 기존 (v2): api-vod-kr.kollus.com/api/v0
  • 변경 (v3): c-api-kr.kollus.com/api
  • 주의: 업로드 기능은 별도 호스트인 upload.kr.kollus.com을 사용합니다.

2. 표준 HTTP 메서드 적용​

v1의 POST 일방향 구조에서 RESTful 표준 명세에 맞춘 HTTP 메서드로 전환되었습니다.

  • 조회: GET
  • 생성: POST
  • 수정: PUT
  • 삭제: DELETE

3. 식별자 타입 변경 (Integer → String)​

모든 리소스의 식별자(ID) 형식이 정수형에서 문자열(Key) 형식으로 변경되었으며, 언어 코드 등도 표준 규격을 따릅니다.

  • media_content_id (Integer) → upload_file_key (String)
  • media_profile_id (Integer) → media_profile_key (String)
  • language_id (예: 2) → language_code (예: "ko")

4. 응답 구조 및 성공 판정 기준 변경​

성공 여부를 판단하는 방식이 HTTP 상태 코드로 일원화되었으며, 응답 데이터 구조(포맷)가 단순화되었습니다.

  • 성공 판정: 기존 error === 0 검사 → HTTP 상태 코드 (200 또는 201) 검사
  • 응답 포맷: { error, message, result } → { data } 구조로 래핑
v2 에러 처리 예외 사항

HTTP 200 응답 내 error: 1 규칙은 v1에만 해당합니다. v2는 HTTP 표준 상태 코드(404, 422 등)와 Laravel 스타일의 { message, errors } 구조로 응답합니다.

5. 경로 파라미터 구조 변경​

채널과 콘텐츠 간의 관계 설정 시, 기존 요청 본문에 포함되던 식별자 상호작용이 URL 경로(Path) 구조로 변경되었습니다.

  • 기존 (v1/v2): channel_key 정보를 요청 본문에 포함하여 전송
  • 변경 (v3): channel_key와 upload_file_key를 모두 URL 경로 파라미터에 포함하여 요청 (참고 문서: 채널 관리)

기능별 엔드포인트 인덱스​

마이그레이션이 필요한 기능의 카테고리를 선택하면 상세 매핑 페이지로 이동합니다. 각 상세 페이지는 기존 버전 대비 변경 사항을 우선적으로 제공합니다.

카테고리포함 기능비고
공통국가, 언어, 타임존 목록 조회국가 및 타임존 목록 조회는 v3 신규 기능
카테고리 관리카테고리 목록 조회/생성/수정/삭제, 채널 연결/연결 해제v2는 카테고리-채널 연결/연결 해제 기능만 지원
채널 관리채널 목록 조회/생성/수정/삭제, 콘텐츠 또는 플레이어 스킨 연결, 콜백 및 보안키 위치 주의
미디어 콘텐츠 키 관리콘텐츠 키 정보 조회, 유효성 검사, 콘텐츠 할당콘텐츠 키 교체 기능은 v3에서 폐기
미디어 인증 관리Kollus 암호화, 사용자 키 생성/재발급/삭제, 워터마킹 식별 코드 조회v2 미지원
콘텐츠 관리콘텐츠 목록 조회/상세 조회, 수정/삭제, 활성화/비활성화, 카테고리 변경, 업로드 URL 생성, 포스터/원본 파일 다운로드메타데이터 조회/수정, 스냅샷 생성/다운로드(v2 전용) 기능은 v3에서 폐기
트랜스코딩 관리트랜스코딩 진행 상태 조회, 추가 트랜스코딩 작업 생성, 트랜스코딩 파일 조회/다운로드/활성화/비활성화/삭제v2 미지원
AI 서비스AI자막 생성, AI요약·챕터 조회/생성, AI배속 전환v3 신규 기능
자막 관리자막 목록 조회/상세 조회, 등록/업로드/수정/삭제, 표시 순서 변경, 지원 언어 목록 조회텍스트 직접 입력 등록 및 자막 상세 조회는 v2부터 지원
북마크 관리북마크 목록 조회(업로드 파일 키/미디어 콘텐츠 키 기준), 추가/수정/삭제v1은 미지원, v2는 목록 조회만 제한적으로 지원
인코딩 프로파일 관리지원 규격/프리셋/그룹 조회, 프로파일 목록 조회/상세 조회/생성/수정, 카테고리 연결/해제v2 미지원
중복 재생 차단 관리중복 재생 차단 기록 조회, 허용 기기 조회/삭제/전체 초기화v3 신규 기능
플레이어 관리플레이어 스킨 목록 조회/삭제, 플레이어 이벤트 목록 조회/삭제v3 신규 기능
통계전체/채널 콘텐츠 시청 순위 조회, 일별 통계 조회시청 순위 조회는 최상위 키로 result_data 사용
태그 관리태그별 콘텐츠 목록 조회, 태그 추가/제거v1 전용

마이그레이션 기술 지원​

마이그레이션 진행 중 문제가 발생하거나 궁금한 사항이 있는 경우 Kollus 기술 지원팀(tech_support@catenoid.net)으로 문의해 주세요. 신속하고 정확한 지원을 위해 문의 시 아래의 필수 정보를 함께 기재해 주세요.

필수 기재 사항​

  1. 현재 사용 중인 API 버전 (v1 또는 v2)
  2. 문제가 발생하는 엔드포인트 URL
  3. 에러 로그, 응답 메시지 및 재현 절차