업로드 API

고객사는 업로드 API를 사용하여 웹사이트 내에 콘텐츠 업로드 기능을 직접 구현할 수 있습니다.

고객사 서버는 업로드 API를 통해 일회용 업로드 URL과 업로드 파일 키를 발급받아 업로드 페이지를 구성합니다. 고객사 운영자가 브라우저에서 파일을 선택하면 해당 파일은 Kollus 업로드 서버로 전송됩니다.

---

유의 사항

• 일회성 세션: 발급된 업로드 URL과 업로드 파일 키는 1회만 사용 가능합니다.
• 만료 정책: 지정된 유효 시간 경과 시 해당 세션은 즉시 무효화됩니다.
• 보안: API 호출 시 발급되는 모든 토큰 및 키 정보가 외부에 노출되지 않도록 주의하세요.

---

업로드 흐름

1. 업로드 페이지 접속: 고객사 운영자가 자체 웹사이트의 동영상 업로드 메뉴에 접근합니다.
2. 업로드 URL 생성: 고객사 서버가 업로드 API를 호출하여 업로드 URL, 업로드 파일 키, 만료 일시 정보를 획득합니다.
3. 업로드 페이지 구성: 고객사 서버는 수신한 정보를 활용하여 파일 선택 및 전송을 위한 UI를 구성합니다.
4. 파일 전송: 고객사 운영자가 파일을 업로드하면 해당 파일은 Kollus 업로드 서버로 전송됩니다. (실시간 진행률 확인 가능)

---

업로드 URL 생성 API

업로드 페이지에서 파일 전송 시 사용할 일회용 업로드 URL을 발급받는 API입니다.

요청 규격

전송 방식

구분	상세
Method	POST
Protocol	HTTP(80), HTTPS(443)
Endpoint	일반 업로드: https://c-api-kr.kollus.com/api/upload/create-url 패스스루 업로드: https://upload.kr.kollus.com/api/v1/create_url
Auth	쿼리 파라미터 kollus_api_access_token(인증 토큰) 전달 필수 확인 경로: Kollus VOD 콘솔 > [서비스 계정] > [API]

요청 본문

JSON 형식으로 본문을 구성합니다.

파라미터	타입	기본값	설명
expire_time	integer	600	업로드 URL 유효 시간 설정 범위: 0~21600 초
category_key	string	-	업로드 파일이 저장될 카테고리 키 (미지정 시 '기본' 카테고리에 저장) 확인 경로: Kollus VOD 콘솔 > [라이브러리] > 좌측 카테고리 목록 [더보기 (⋮)] > [카테고리 키 복사]
title	string	-	콘텐츠 제목 (미지정 시 파일 이름 사용) 패스스루 업로드 시에는 원본 파일 이름으로 강제 적용됩니다.
is_encryption_upload	integer	0	콘텐츠 암호화 여부 0: 일반 업로드 1: 암호화 업로드 (Security Pack 계약 필수, HTML5 Player for All 미지원)
is_audio_upload	integer	0	업로드 파일 유형 0: 비디오 1: 오디오
is_passthrough	integer	0	업로드 방식 0: 일반 업로드 1: 패스스루 업로드 (원본 파일 그대로 서비스)
profile_key	string	-	(패스스루 업로드 시 필수) 인코딩 프로파일 키 확인 경로: Kollus VOD 콘솔 > [설정] > [인코딩 프로파일]

요청 예시

{
  "expire_time": 600,
  "category_key": "abcd1234",
  "title": "My Video",
  "is_encryption_upload": 0,
  "is_audio_upload": 0
}

응답 규격

업로드 URL 생성 API의 응답은 application/json; charset=UTF-8 형식을 준수합니다. 업로드 방식(일반/패스스루)에 따라 응답 객체의 명칭이 상이하므로 구현 시 주의하세요.

일반 업로드 응답 필드

필드	설명
error	처리 결과 (0: 정상)
message	에러 메시지 (정상 처리 시 빈 문자열)
data	업로드 세션 정보를 포함하는 객체
data.upload_url	업로드 서버 URL
data.progress_url	업로드 진행률 조회 URL
data.upload_file_key	업로드 파일 키
data.expired_at	업로드 파일 키 만료 일시 (Unix Timestamp)

일반 업로드 응답 예시

{
  "error": 0,
  "message": "",
  "data": {
    "upload_url": "https://upload.kr.kollus.com/api/v1/UploadMultiParts/KUS_S5yb4bgc5aGquWzhatk1cOAo9zTZnAv7/20151218-oyn7ytrh",
    "progress_url": "https://upload.kr.kollus.com/api/v1/GetUploadingProgress/KUS_S5yb4bgc5aGquWzhatk1cOAo9zTZnAv7",
    "upload_file_key": "20151218-oyn7ytrh",
    "expired_at": 1413883670
  }
}

패스스루 업로드 응답 필드

필드	설명
error	처리 결과 (0: 정상)
message	에러 메시지 (정상 처리 시 빈 문자열)
result	패스스루 업로드 세션 정보를 포함하는 객체
result.upload_url	업로드 서버 URL
result.progress_url	업로드 진행률 조회 URL
result.upload_file_key	업로드 파일 키
result.will_be_expired_at	업로드 파일 키 만료 일시 (Unix Timestamp)

패스스루 업로드 응답 예시

{
  "error": 0,
  "message": "",
  "result": {
    "upload_url": "https://upload.kr.kollus.com/api/v1/UploadMultiParts/KUS_BOHG2eTQhPSIaG2511G1jfkpWOYAOjDc/20151204-dh6o2goz",
    "progress_url": "https://upload.kr.kollus.com/api/v1/GetUploadingProgress/KUS_BOHG2eTQhPSIaG2511G1jfkpWOYAOjDc",
    "upload_file_key": "20141017-y4sae7td",
    "will_be_expired_at": 1413883670
  }
}

---

파일 업로드

발급받은 upload_url을 엔드포인트로 지정하고, HTML multipart/form-data 형식을 사용하여 실제 파일을 전송합니다.

구현 가이드

• 파라미터 키 고정: 파일 input 요소의 name 속성은 반드시 upload-file로 설정해야 합니다.
• 단일 파일 제약: 하나의 upload_url은 오직 하나의 파일만 전송 가능합니다. (중복 전송 시 실패 처리)
• 성공 판정 기준: 파일 전송 완료 시점이 URL 만료 일시 이전이어야 업로드 성공으로 판정됩니다. 대용량 파일 업로드 시 네트워크 환경을 고려하여 expire_time을 충분히 길게 설정하세요.

요청 규격

요청 본문

파라미터	타입	기본값	설명
return_url	string	-	업로드 완료 후 리다이렉트될 URL 결과값 result, message가 Query String으로 추가됩니다. 예: https://foo.com/result.html?result=S&message=... result S: 업로드 성공 F: 업로드 실패 message: 결과 알림 메시지
disable_alert	integer	0	업로드 완료 시 브라우저 알림창 노출 여부 0: 노출 1: 비노출
redirection_scope	string	outer	리다이렉션 대상 outer: window.top.location (최상위 창) inner: window.location (현재 창) no: 리다이렉션을 수행하지 않음
accept	string	text/html	응답 데이터 형식 text/html: 위 옵션들이 반영된 HTML 페이지 반환 application/json: 옵션 무시 후 JSON 데이터 반환

요청 예시

<form action="https://upload.kr.kollus.com/20141017-y4sae7td" method="post" enctype="multipart/form-data">
  <input type="hidden" name="redirection_scope" value="outer" />
  <input type="hidden" name="return_url" value="https://www.foobar.com/upload_result.html" />
  <input type="hidden" name="disable_alert" value="1" />

  <input type="file" name="upload-file" />
  <input type="submit" />
</form>

---

업로드 진행률 조회

현재 진행 중인 파일 전송 상태를 실시간으로 모니터링할 수 있습니다. 업로드 URL 생성 시 응답받은 progress_url을 주기적으로 호출하여 정보를 획득합니다.

응답 규격

응답 필드

• Content-Type : application/json; charset=UTF-8

필드	설명
error	처리 결과 (0: 정상)
message	현재 세션의 상태 메시지
result	진행률 데이터를 포함하는 객체
result.progress	현재 업로드 진행률 (0~100%)

응답 예시

{
  "error": 0,
  "message": "OK",
  "result": {
    "progress": 5
  }
}