WECANDEO로 이동
APIs

VIDEOPACK API 사용하기

WECANDEO API 사용하기

VIDEOPACK API는 웹사이트 또는 어플리케이션에 미디어 업로드 및 인코딩, 관리, 동영상 재생 등을 REST API로 사용합니다.

VIDEOPACK API 진행과정

• 동영상 폴더 조회 API를 사용하여 폴더(업로드할 공간) ID를 조회합니다. [폴더 조회]

• 업로드 토큰 요청 API를 사용하여 파일 업로드를 진행할 수 있는 토큰을 리턴받습니다. [업로드 토큰 요청]

• 동영상 파일 업로드 API를 사용하여 각 장르별 동영상을 폴더에 업로드합니다. [업로드]

• 동영상 업로드 진행 조회 API와 동영상 업로드 상태 조회 API를 사용하여 특정 간격으로 동영상 업로드 상태를 확인합니다. [업로드 상태조회]

• 업로드 후 사용자 지정 썸네일 이미지와 자막을 업로드합니다.(썸네일이미지 업로드 API, 자막파일 업로드 API를 참조 바랍니다.) [업로드 완료 후 시점 무관]

• 배포 패키지 목록 조회 API를 사용하여 인코딩이 진행될 동영상 패키지ID를 조회합니다. [패키지 조회]

• 배포 패키지에 동영상 추가 API를 사용하여 인코딩을 진행합니다. [패키지에 동영상 추가]

• 패키지에 동영상이 추가되면 WECANDEO 인코더 서버가 자체적으로 인코딩을 시작합니다. [인코딩]

• 동영상 인코딩 상태 조회 API를 사용하여 인코딩이 완료되었음을 확인합니다. [인코딩 상태 조회]

• 인코딩 완료 후에 서비스가 가능한 영상 URL을 제공합니다. [Play URL 생성]

• 동영상 배포 코드 조회 API를 사용하여 배포주소(Play URL/Video URL)를 확인하고 서비스에 적용합니다. [배포 적용하기]

• 동영상 폴더 조회 API를 사용하여 폴더(업로드할 공간) ID를 조회합니다. [폴더 조회]

• 배포 패키지 목록 조회 API를 사용하여 인코딩이 진행될 동영상 패키지ID를 조회합니다. [패키지 조회]

• 업로드 토큰 요청 API를 사용하여 파일 업로드를 진행할 수 있는 토큰을 리턴받습니다. [업로드 토큰 요청]

• 동영상 파일 업로드 API를 사용하여 각 장르별 동영상을 폴더에 업로드합니다. (‘1안’과의 차이점으로 동영상 파일 업로드 API에 패키지 아이디를 추가하여 인코딩까지 자동진행 합니다.) [업로드]

• 동영상 인코딩 상태 조회 API를 사용하여 인코딩이 완료되었음을 확인합니다. [인코딩 상태 조회]

• 썸네일 이미지와 자막을 업로드합니다.(썸네일이미지 업로드 API, 자막파일 업로드 API) [업로드 완료 후 시점 무관]

• 인코딩 완료 후에 서비스가 가능한 영상 URL을 제공합니다. [Play URL 생성]

• 동영상 배포 코드 조회 API를 사용하여 배포주소(Play URL/Video URL)를 확인하고 서비스에 적용합니다. [배포 적용하기]

  • 폴더 조회
    동영상 폴더는 동영상이 업로드 되는 저장 공간입니다.

동영상 폴더 목록 조회 API를 사용하여 동영상 폴더 목록을 조회할 수 있습니다.

curl -H "x-api-key: {API Key}" https://api.v4.wecandeo.com/info/videopack/folder/v1/info.json

{
	"folderList":[
    {
      "id": 6,
      "cdate": "2023-05-04T11:35:09.000Z",
      "folderName": "Sample Folder",
      "videoCnt": 5,
      "folderSize": 99995350
    },
    {
      "id": 18,
      "cdate": "2023-05-10T08:13:36.000Z",
      "folderName": "TestVideo",
      "videoCnt": 0,
      "folderSize": 0
    },
    {
      "id": 19,
      "cdate": "2023-05-10T09:29:32.000Z",
      "folderName": "TestVideo2",
      "videoCnt": 0,
      "folderSize": 0
    }
	]
}
  • 패키지 조회
    배포 패키지는 동영상이 인코딩 되는 공간입니다. 배포 패키지에 대한 자세한 설명은 배포 패키지 생성을 참조하시기 바랍니다.

배포 패키지 목록 조회 API를 사용하여 배포 패키지의 목록을 조회할 수 있습니다.

curl -H "x-api-key: {API Key}" https://api.v4.wecandeo.com/info/videopack/package/v1/info.json

{
  "packageList":[
    {
      "packageId": 14,
      "packageType": "NONE",
      "packageName": "Sample Package"
    }
  ]
}

업로드 토큰 요청

사용자 인증과 업로더 할당에 필요한 업로드 토큰 요청 API를 사용하여 파일 업로드 요청 시 필요한 파라미터인 ‘token’과 ‘uploadUrl’값을 리턴받습니다.

자세한 사항은 업로드 토큰 API를 참조하시기 바랍니다.

curl -H "x-api-key: {API Key}" https://api.v4.wecandeo.com/info/videopack/upload/v1/token.json

{
	"ver": "v1",
	"uploadUrl": "https://upload.v4.wecandeo.com/v1/upload",
	"token": "752e4f77-8505-40ec-a4b2-05b512d1cecb"
}

동영상 파일 업로드

동영상 파일 업로드 API는 업로드 토큰 요청 API에서 리턴받은 ‘token’, ‘uploadUrl’와 동영상 폴더 생성 API에서 리턴받은 ‘folderId’, 동영상 파일을 multipart/form-data 타입으로 서버에 전송하여 업로드 – 인코딩 – 배포의 일련의 과정을 진행할 수 있습니다.

자세한 사항은 동영상 파일 업로드 API를 참조하시기 바랍니다.

curl -F folder={folderID} -F videofile=@{video_path/video_file_name} {uploadUrl}?token={token}

{
  "status": "COMPLETE",
  "uploadInfo":{
    "uploadDetail":{
      "videoHeight": 720,
      "videoWidth": 1280,
      "duration": 59234,
      "videoFramerate": 30.0,
      "accessKey": "PXqGis2mA8NoqTAlzWiiQ8BvdA8YF61h6is"
		},
		"errorInfo":{
			"errorCode": "None",
			"errorMessage": ""
		},
		"thumbnails":[
      {"seq": 0, "sel": false, "url": "https://{Domain}/thumb/20230510/18/53014b64-db08-4b5a-b711-4174621adc44_f7bc3386-f978-495f-8acd-944e69ef026b.jpg",…},
      {"seq": 1, "sel": false, "url": "https://{Domain}/thumb/20230510/18/53014b64-db08-4b5a-b711-4174621adc44_f6448e9d-836a-4e99-a428-264b623bf89b.jpg",…},
      {"seq": 2, "sel": true, "url": "https://{Domain}/thumb/20230510/18/53014b64-db08-4b5a-b711-4174621adc44_869ab9de-c0e2-4aed-bcf3-645a42473847.jpg",…},
      {"seq": 3, "sel": false, "url": "https://{Domain}/thumb/20230510/18/53014b64-db08-4b5a-b711-4174621adc44_763c9233-c79a-4e7f-97d4-d7b459937d00.jpg",…},
      {"seq": 4, "sel": false, "url": "https://{Domain}/thumb/20230510/18/53014b64-db08-4b5a-b711-4174621adc44_48ac56fb-9c20-485d-97fe-77fb7477d4e1.jpg",…},
      {"seq": 5, "sel": false, "url": "https://{Domain}/thumb/20230510/18/53014b64-db08-4b5a-b711-4174621adc44_5f6524b7-5693-4564-a22a-0ca3ca055cdc.jpg",…}
		]
	}
}

파일 업로드 API v1, v2의 차이

v1

동영상 파일 업로드 API v1은 파일 업로드 이후 썸네일 이미지 추출까지 완료가 되어야 결과 값을 반환합니다.
결과값으로 리턴받은 ‘access key’를 사용하여 커스텀 썸네일, 자막파일 업로드가 가능합니다.

v2

동영상 파일 업로드 API v2는 위의 그림처럼 파일 업로드 완료 후 즉시 결과 값을 반환하고, 썸네일 이미지 추출은 비동기로 진행합니다.
결과값으로 리턴받은 ‘access key’를 사용하여 커스텀 썸네일, 자막파일 업로드가 가능합니다.

🚧

동영상 파일 업로드 API v2를 사용하여 업로드하는 경우에만 동영상 업로드 진행 조회 API의 업로드 진행률(progress)이 100%가 된 후에 access key가 리턴되고 해당 access key를 확인 후 추가 작업(커스텀 썸네일, 자막파일 업로드 등)을 진행할 수 있습니다.

자세한 사항은 동영상 파일 업로드 API를 참조하시기 바랍니다.

인코딩 추가 진행하기

배포 패키지 목록 조회 API에서 리턴받은 packageId 값을 파라미터로 추가하면

업로드 과정이 모두 완료된 후 해당 패키지에 동영상 파일을 추가하여 인코딩도 자동 진행됩니다.

📘

원본 삭제 옵션

  • 동영상 파일 업로드 API에서 orgFileDel 파라미터를 추가하면 인코딩된 동영상 파일만 남아있고, 원본 영상은 자동 삭제됩니다. 스토리지 비용을 절약할 수 있지만, 원본이 삭제되면 인코딩 추가 및 변경이 불가능합니다.
  • 패키지ID가 파라미터에 추가되었을 경우에만 원본삭제가 적용됩니다.

추후에 원본삭제가 필요하실 경우 CMS에서 조건부삭제기능을 사용하여 원본삭제가 가능합니다.

📘

업로드 콜백

  • 동영상 파일 업로드 API에서 callback 파라미터를 추가하면, 업로드 완료 결과값을 callback url에 해당하는 서버에 GET {Callback URL}?data={Response JSON String} 형식으로 302 리다이렉트 응답합니다.

📌 동영상 파일 업로드에 자동으로 진행되는 썸네일 이미지 추출 이외에 사용자가 지정하는 썸네일을 업로드 하는 기능입니다.

썸네일 업로드를 위한 업로드 주소와 토큰을 발급해야 합니다.

curl -H "x-api-key: {API Key}" https://api.v4.wecandeo.com/info/videopack/thumbnail/v1/upload/token.json?accessKey={accessKey}

{
	"ver": "v1",
	"token": "{TOKEN}",
	"uploadUrl": "{thumbnailUploadUrl}"
}

업로드 주소와 토큰을 이용하여 업로드 합니다.

curl -F file=@{thumbnailfile_path/thumbnail_file_name} {thumbnailUploadUrl}?token={token}

{
	"isSuccess": true
}
  • 자막 파일의 언어코드 조회하기

자막 파일 언어코드 조회하기 API를 사용하여 자막 파일 업로드 시에 언어코드를 확인할 수 있습니다.

curl -H "x-api-key: {API Key}" https://api.v4.wecandeo.com/info/videopack/caption/v1/language.json

{
  "caption":{
    "language":[
      {"id": 1, "code": "ko", "language": "한국어"},
      {"id": 2, "code": "en", "language": "English"},
      {"id": 3, "code": "ja", "language": "日本語"},
      ...
    ]
  }
}
  • 자막 파일 업로드

자막 파일 업로드는 동영상 파일 업로드가 완료된 후에 동영상 파일에서 사용하는 자막 파일을 업로드 하는 기능입니다.

자막 파일 업로드를 위한 업로드 주소와 토큰을 발급해야 합니다.

curl -H "x-api-key: {API Key}" https://api.v4.wecandeo.com/info/videopack/caption/v1/upload/token.json?accessKey={accessKey}

{
	"ver": "v1",
	"token": "{TOKEN}",
	"uploadUrl": "{captionUploadUrl}"
}

업로드 주소와 토큰을 이용하여 업로드 합니다.

추가로 언어코드를 추가하시면 해당 언어코드로 업로드가 됩니다.

curl -F  file=@{captionfile_path/caption_file_name} -F langId={langId} {captionUploadUrl}?token={token}

{
	"isSuccess": true
}
  • 배포 패키지에 동영상 추가
    인코딩 준비완료된 동영상을 배포 패키지에 추가하여 인코딩합니다.

자세한 설명은 배포 패키지에 동영상 추가 API를 참조하시기 바랍니다.

curl -H "x-api-key: {API Key}" https://api.v4.wecandeo.com/info/videopack/package/v1/set/include.json?accessKey={access_key}&packageId={package id}

{
    "setPackage": {
        "status": "Success"
    }
}

📘

인코딩 완료 콜백

CMS VIDEOPACK 관리자 화면의 [배포 > 배포 패키지 > 해당 패키지 클릭 > 배포 설정 > Callback URL]에 URL 입력 후 Callback URL을 설정하면 인코딩 완료 후에 인코딩 성공 여부 등을 리턴받을 수 있습니다.

통계

VIDEOPACK은 사용자 시청에 대한 통계수집 기능이 내장되어 있습니다.

이 수집기능은 WECANDEO 통계 시스템에 시청자 분석 데이터를 전달하고, 수집된 데이터는 가공되어 분석 리포트 API(사용량 통계, 재생 통계)로 결과를 리턴합니다.

WECANDEO Player가 아닌 커스텀 플레이어를 사용할 경우에도 플레이어 안에 WECANDEO 통계 스크립트를 내장하여 WECANDEO 통계 시스템을 사용하실 수 있습니다.

커스텀 플레이어를 사용하시는 경우 VIDEO STATISTICS GUIDE를 참조하시기 바랍니다.