WECANDEO API 사용하기
VIDEOPACK API는 웹사이트 또는 어플리케이션에 미디어 업로드 및 인코딩, 관리, 동영상 재생 등을 REST API로 사용합니다.
VIDEOPACK API 진행과정
• 업로드 토큰 요청 API를 사용하여 파일 업로드를 진행할 수 있는 토큰을 리턴받습니다. [업로드 토큰 요청]
• 동영상 파일 업로드 API를 사용하여 각 장르별 동영상을 폴더에 업로드합니다. [업로드]
• 동영상 업로드 진행 조회 API와 동영상 업로드 상태 조회 API를 사용하여 특정 간격으로 동영상 업로드 상태를 확인합니다. [업로드 상태조회]
• 업로드 후 사용자 지정 썸네일 이미지와 자막을 업로드합니다.(썸네일이미지 업로드 API, 자막파일 업로드 API를 참조 바랍니다.) [업로드 완료 후 시점 무관]
• 배포 패키지 목록 조회 API를 사용하여 인코딩이 진행될 동영상 패키지ID를 조회합니다. [패키지 조회]
• 배포 패키지에 동영상 추가 API를 사용하여 인코딩을 진행합니다. [패키지에 동영상 추가]
• 패키지에 동영상이 추가되면 WECANDEO 인코더 서버가 자체적으로 인코딩을 시작합니다. [인코딩]
• 동영상 인코딩 상태 조회 API를 사용하여 인코딩이 완료되었음을 확인합니다. [인코딩 상태 조회]
• 인코딩 완료 후에 서비스가 가능한 영상 URL을 제공합니다. [Play URL 생성]
• 동영상 배포 코드 조회 API를 사용하여 배포주소(Play URL/Video URL)를 확인하고 서비스에 적용합니다. [배포 적용하기]
• 배포 패키지 목록 조회 API를 사용하여 인코딩이 진행될 동영상 패키지ID를 조회합니다. [패키지 조회]
• 업로드 토큰 요청 API를 사용하여 파일 업로드를 진행할 수 있는 토큰을 리턴받습니다. [업로드 토큰 요청]
• 동영상 파일 업로드 API를 사용하여 각 장르별 동영상을 폴더에 업로드합니다. (‘1안’과의 차이점으로 동영상 파일 업로드 API에 패키지 아이디를 추가하여 인코딩까지 자동진행 합니다.) [업로드]
• 동영상 인코딩 상태 조회 API를 사용하여 인코딩이 완료되었음을 확인합니다. [인코딩 상태 조회]
• 썸네일 이미지와 자막을 업로드합니다.(썸네일이미지 업로드 API, 자막파일 업로드 API) [업로드 완료 후 시점 무관]
• 인코딩 완료 후에 서비스가 가능한 영상 URL을 제공합니다. [Play URL 생성]
• 동영상 배포 코드 조회 API를 사용하여 배포주소(Play URL/Video URL)를 확인하고 서비스에 적용합니다. [배포 적용하기]
- 폴더 조회
동영상 폴더는 동영상이 업로드되는 저장공간입니다.
동영상 폴더 목록 조회 API를 사용하여 동영상 폴더 목록을 조회할 수 있습니다.
curl http://api.wecandeo.com/info/v1/folders.json?key={api_key}
{
"folderList": {
"errorInfo": {
"errorCode": "None",
"errorMessage": ""
},
"list": [
{
"id": 2011351,
"folder_name": "Sample Folder",
"video_cnt": 1,
"folder_size": 30628292,
"cdate": 1593407334000,
"package_cnt": 1
}
]
}
}
- 패키지 조회
배포 패키지는 동영상이 인코딩되는 공간입니다. 배포 패키지에 대한 자세한 설명은 배포 패키지 생성을 참조하시기 바랍니다.
배포 패키지 목록 조회 API를 사용하여 배포 패키지의 목록을 조회할 수 있습니다.
curl https://api.wecandeo.com/info/v1/packages.json?key={API key}
{
"packageList": {
"packageList": [
{
"package_id": 1013201,
"package_name": "Sample Package",
"package_auth": "N",
"opt": "NONE"
}
],
"errorInfo": {
"errorCode": "None",
"errorMessage": ""
}
}
}
업로드 토큰 요청
사용자 인증과 업로더 할당에 필요한 업로드 토큰 요청 API를 사용하여 파일업로드 요청 시 필요한 파라미터인 ‘token’과 ‘uploadUrl’값을 리턴받습니다.
자세한 사항은 업로드 토큰 API를 참조 하시기 바랍니다.
curl https://api.wecandeo.com/web/v4/uploadToken.json?key={API key}
{
"uploadInfo": {
"uploadUrl": "https://upload-03.wecandeo.com/v4/upload",
"errorInfo": {
"errorCode": "None",
"errorMessage": ""
},
"uploadCancelUrl": "https://upload-03.wecandeo.com/uploadCancel.json",
"captionUploadUrl": "https://upload-03.wecandeo.com/caption/upload",
"token": "rm8KbqpwHgYjjKtr1QMA484StFq6ZvCn",
"adUploadUrl": "https://upload-03.wecandeo.com/ad/upload",
"thumbnailUploadUrl": "https://upload-03.wecandeo.com/upload/image/thumbnail"
}
}
동영상 파일 업로드
동영상 파일 업로드 API는 업로드 토큰 요청 API에서 리턴받은 ‘token’, ‘uploadUrl’와 동영상 폴더 생성 API에서 리턴받은 ‘folderId’, 동영상 파일을 multipart/form-data 타입으로 서버에 전송하여 업로드 – 인코딩 – 배포의 일련의 과정을 진행할 수 있습니다.
자세한 사항은 동영상 파일 업로드 API를 참조하시기 바랍니다.
curl -F folder={folderID} -F videofile=@{video_path/video_file_name} {uploadUrl}?token={token}
{
"uploadInfo": {
"uploadDetail": {
"duration": 30600,
"video_height": 270,
"access_key": "pEcVt1O8bKYCCyfgUEFSisOR661rZQeH5Z2AzAeanDToie",
"video_width": 480,
"video_framerate": 30.0
},
"errorInfo": {
"errorCode": "None",
"errorMessage": ""
}
}
}
파일 업로드 API v3, v4의 차이
v3
동영상 파일 업로드 API v3는 위의 그림처럼 파일 업로드, 썸네일 이미지 추출완료 후 결과값을 리턴해줍니다.
결과값으로 리턴받은 ‘access key’를 사용하여 커스텀 썸네일, 자막파일 업로드가 가능합니다.
v4
동영상 파일 업로드 API v4는 위의 그림처럼 파일 업로드 후 결과값을 보내주고, 그 외에 썸네일 이미지 추출 프로세스는 추가로 실행됩니다.
결과값으로 리턴받은 ‘access key’를 사용하여 커스텀 썸네일, 자막파일 업로드가 가능합니다.
동영상 파일 업로드 API v4를 사용하여 업로드하는 경우에만 동영상 업로드 진행 조회 API의 업로드 진행율(process)이 100%가 된 후에 access key가 리턴되고 해당 access key를 확인 후 추가 작업(커스텀 썸네일, 자막파일 업로드 등)을 진행할 수 있습니다.
자세한 사항은 동영상 파일 업로드 API를 참조하시기 바랍니다.
인코딩 추가 진행하기
배포 패키지 목록 조회 API에서 리턴받은 pkg(패키지ID)값을 파라미터로 추가하면
업로드 과정이 모두 완료된 후 해당 패키지에 동영상 파일을 추가하여 인코딩도 자동진행됩니다.
원본 삭제 옵션
- 동영상 파일 업로드 API에서 orgFileDel 파라미터를 추가하면 인코딩된 동영상 파일만 남아있고, 원본 영상은 자동 삭제됩니다. 스토리지 비용을 절약할 수 있지만, 원본이 삭제되면 인코딩 추가 및 변경이 불가능합니다.
- 패키지ID가 파라미터에 추가되었을 경우에만 원본삭제가 적용됩니다.
추후에 원본삭제가 필요하실 경우 CMS에서 조건부삭제기능을 사용하여 원본삭제가 가능합니다.
업로드 콜백
- 동영상 파일 업로드 API에서 callback 파라미터를 추가하면, 업로드 완료 결과값을 callback url에 해당하는 서버에 GET {Callback URL}?data={Response JSON String} 형식으로 302 리다이렉트 응답합니다.
- 썸네일 이미지 업로드
썸네일 이미지 업로드는 동영상에 대한 썸네일을 업로드 하는 기능입니다.
썸네일 이미지 업로드에는 ‘token’, ‘access key’, ‘thumbnailUploadUrl’이 필요합니다.
📌 동영상 파일 업로드에 자동으로 진행되는 썸네일 이미지 추출 이외에 사용자가 지정하는 썸네일을 업로드 하는 기능입니다.
curl -F captionfile=@{thumbnailfile_path/thumbnail_file_name} -F token={token} -F access_key={access_key} {thumbnailUploadUrl}?token={token}
{
"uploadInfo": {
"errorInfo": {
"errorCode": "None",
"errorMessage": ""
},
"thumbnails": [
{
"playtime": 0,
"seq": 100,
"url": "http://timgs.wecandeo.com/thumb/3417/20200630/17/V10187477_0506_ba4fc25_00000.jpg"
}
]
}
}
- 자막파일의 언어코드 조회하기
자막 파일 언어코드 조회하기 API를 사용하여 자막파일 업로드 시에 언어코드를 확인할 수 있습니다.
curl https://api.wecandeo.com/info/v1/video/caption/language.json?key={API key}
{"captionLanguage":{"errorInfo":{"errorCode":"None","errorMessage":""},"language":[{"id":10000,"code":"ko","language":"한국어"},{"id":10001,"code":"en","language":"English"},{"id":10002,"code":"ja","language":"日本語"},{"id":10003,"code":"zh","language":"中文(简体)"},
⋮
- 자막파일 업로드
자막파일 업로드는 동영상 파일 업로드가 완료된 후에 동영상 파일에서 사용하는 자막파일을 업로드 하는 기능입니다.
자막파일 업로드에는 업로드 토큰, access key가 필요합니다.
curl -F captionfile=@{captionfile_path/caption_file_name} {captionUploadUrl}?token={token}&access_key={access_key}&lang_id={lang_id}
{
"uploadInfo": {
"uploadDetail": {
"access_key": "pEcVt1O8bKYCCyfgUEFSisOR661rZQeH5Z2AzAeanDToie",
"format": "VTT"
},
"errorInfo": {
"errorCode": "None",
"errorMessage": ""
}
}
}
- 배포 패키지에 동영상 추가
인코딩 준비완료된 동영상을 배포 패키지에 추가하여 인코딩합니다.
자세한 설명은 배포 패키지에 동영상 추가 API를 참조하시기 바랍니다.
curl https://api.wecandeo.com/info/v1/video/set/package.json?key={API key}&access_key={access_key}&pkg={package id}
{
"setPackage": {
"errorInfo": {
"errorCode": "None",
"errorMessage": ""
},
"status": "Success"
}
}
인코딩 완료 콜백
CMS VIDEO PACK 관리자 화면의 [ 배포 > 배포 패키지 > 해당 패키지 클릭 > 배포 설정 > Callback URL ]에 URL 입력 후 배포 설정 적용하기를 클릭하시면 인코딩 완료 후에 인코딩 성공 여부 등을 리턴받을 수 있습니다.
통계
VIDEOPACK은 사용자 시청에 대한 통계수집 기능이 내장되어 있습니다.
이 수집기능은 WECANDEO 통계 시스템에 시청자 분석 데이터를 전달하고, 수집된 데이터는 가공되어 분석 리포트 API(스토리지 사용량 조회 API, 트래픽 사용량 조회 API, 플레이어 API)로 결과를 리턴합니다.
WECANDEO Player가 아닌 커스텀 플레이어를 사용할 경우에도 플레이어 안에 WECANDEO 통계 스크립트를 내장하여 WECANDEO 통계 시스템을 사용하실 수 있습니다.
커스텀 플레이어를 사용하시는 경우 VIDEO STATISTICS GUIDE를 참조하시기 바랍니다.