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@kollus.com)으로 문의해 주세요. 신속하고 정확한 지원을 위해 문의 시 아래의 필수 정보를 함께 기재해 주세요.

필수 기재 사항

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