패키징 API 가이드

PallyCon 워터마크 패키징 서비스는 클라우드 SaaS 형태로 제공되는 워터마크 삽입 서비스입니다. CLI 임베더 또는 임베더 라이브러리를 이용한 별도의 서버를 구축할 필요 없이, 인코딩 결과물을 대상으로 PallyCon 클라우드 서비스를 이용하여 API 기반 워터마크 삽입 및 패키징 작업을 수행할 수 있습니다.

sequenceDiagram participant A as 서비스 사이트 participant B as PallyCon 클라우드 A ->> B: 인코딩된 MP4 B -->> B: 워터마크 삽입 opt 멀티DRM 적용 B -->> B: 콘텐츠 암호화 end B ->> A: 패키징 결과물 Note right of B: DASH / HLS 콘텐츠
(각각 0, 1 두벌)

패키징을 위한 스토리지와 작업 관리 API에는 아래와 같은 공통 규격이 사용됩니다.

PallyCon HTTP API 규격

PallyCon 서비스에서 사용하는 각종 HTTP API 요청시 아래 규격을 따릅니다.

요청 규격

Name Value
pallycon-apidata base64 Encoding ( JSON string )

요청 데이터 JSON 포맷

{
    "data":"{base64 encode(aes256 cbc encrypt(API data))}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{base64 encode(sha256(message format))}"
}

요청 데이터 명세

Name Value Required Description
data String Y 각 API마다 정의된 규격으로 생성한 JSON 문자열을 AES 암호화하고, 결과값을 base64 문자열로 입력
timestamp String Y GMT 시간대 기준으로 요청 시점의 시간을 “yyyy-mm-ddThh:mm:ssZ” 포맷으로 입력
hash String Y 아래 규격에 따라 생성한 해시값을 입력

AES256 암호화

AES256 암호화는 PallyCon Cloud 서비스 사이트 생성 시 발급 되는 Site 키 값을 이용하여 아래와 같이 처리 합니다. ( PallyCon 콘솔 사이트에서 확인 )

  • Mode : CBC
  • AES key : 32 byte (PallyCon 콘솔 사이트에서 발급 되는 site key)
  • AES IV : fixed 16 byte (0123456789abcdef)
  • Padding : pkcs7

SHA256 입력 포맷

SHA256 해시의 입력값은 다음과 같은 문자열을 조합해 입력합니다.

  [site access key] + [site_id] + [json.data] + [json.timestamp]
  • site access key: PallyCon Cloud 서비스 사이트 생성 시 발급 되는 access key 값이며 PallyCon 콘솔 사이트에서 확인 가능합니다.
  • sha256 해시 함수의 결과 값은 문자열로 변환하지 않고 바이트 배열 형태 그대로 base64 함수에 입력되어야 합니다.

스토리지 등록 API

워터마크 임베딩과 패키징 작업에 사용되는 스토리지를 등록하는 API입니다. 패키징 작업을 등록하기 전에 먼저 이 API를 통해 작업에 사용될 스토리지를 등록해야 합니다.

요청 규격

  • PallyCon HTTP API 규격으로 호출
  • URL : https://api.pallycon.com/api/v2/storage/[SITE_ID]
  • Method: POST
  • Content type: application/json;charset=UTF-8

URL의 ‘SITE_ID’ 부분은 PallyCon 콘솔 사이트에서 발급된 실제 사이트 ID를 입력해야 합니다.

요청 데이터 JSON 포맷

{
    "storage_name" : "{storage name}",
    "type" : "{storage type}",
    "id": "{access id}",
    "password": "{access password}",
    "aws_bucket": "{bucket name}",
    "description" : "{description}",
    "region": "{region}"
}

요청 데이터 명세

Key type required description
storage_name String Y 스토리지 명
type String Y 스토리지 타입 : 현재 AWS S3만 지원 (‘S3’ 입력)
id String Y 스토리지 접근 ID : aws access key id
password String Y 스토리지 접근 암호 : aws secret access key
aws_bucket String Y 버켓 명
description String N 스토리지 설명
region String Y 스토리지의 AWS 리전 코드

응답 규격

응답 데이터 JSON 포맷

{
    "storage_id": "{storage id}",
    "error_code": "{error code}",
    "error_message": "{error message}"
}

응답 데이터 명세

Key type description
error_code String “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러인 경우 에러 메시지
storage_id String 스토리지 ID

스토리지 수정 API

워터마크 임베딩과 패키징 작업에 사용되는 스토리지 정보를 수정하는 API입니다.

요청 규격

  • PallyCon Cloud HTTP API 규격으로 호출
  • Url: https://api.pallycon.com/api/v2/storage/[SITE_ID]
  • Method: PUT
  • Content type: application/json;charset=UTF-8

요청 데이터 JSON 포맷

{
    "storage_id" : "{storage id}",
    "storage_name" : "{storage name}",
    "description": "{description}"
}

요청 데이터 명세

Key type required description
storage_id String Y 스토리지 ID
storage_name String N 스토리지 명
description String N 스토리지 설명

응답 규격

응답 데이터 JSON 포맷

{
    "storage_id": "{storage id}",
    "error_code": "{error code}",
    "error_message": "{error message}"
}

응답 데이터 명세

Key type description
error_code String “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러인 경우 에러 메시지
storage_id String 스토리지 ID

스토리지 목록 API

등록된 스토리지의 목록를 가져오는 API입니다.

요청 규격

  • PallyCon Cloud HTTP API 규격으로 호출
  • Url : https://api.pallycon.com/api/v2/storage/[SITE_ID]
  • Method : GET
  • Content type : application/json;charset=UTF-8

요청 데이터 JSON 포맷

{
    "search_keyword": "{search keyword}",
    "search_keyword_type": "{storageId/ storageName}",
    "storage_type": "S3",
    "region": "{region}",
    "from": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
    "to": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
    "page_unit": "{long value}",
    "page_index": "{long value}",
    "time_zone": "{hh:mm}"
}

요청 데이터 명세

Key type required description
search_keyword String N 검색어
search_keyword_type String N 검색 타입(storageId, storageName)
storage_type String Y 스토리지 타입 (S3)
from String N 스토리지의 등록 시간 검색 조건
to String N 스토리지의 등록 시간 검색 조건
page_unit Int N 검색 갯수. default : 25
page_index Int N 검색 페이지. default : 1
region String N 스토리지의 AWS Region 코드
time_zone String N 검색 시간대

응답 규격

응답 데이터 JSON 포맷

{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "total_count": "total count",
    "time_zone": "{hh:mm}",
    "data": [{
        "storage_id" : "{storage id}",
        "storage_name" : "{storage name}",
        "type" : "{storage type}",
        "id": "{access id}",
        "password": "{access password}",
        "aws_bucket": "{bucket name}",
        "description" : "{description}",
        "region": "{region}",
        "reg_date": "{YYYY-MM-DD'T'hh:mm:ss'Z'}"
    }]
}

응답 데이터 규격

Key type description
error_code String “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러인 경우 에러 메시지
storage_id String 스토리지 ID

패키징 작업 등록 API

이 API는 새로운 워터마킹 패키징 작업을 등록합니다. 패키징 작업을 등록하기 전에 먼저 작업용 스토리지를 등록하고, 해당 스토리지에 원본 MP4 파일을 업로드해야 합니다.

요청 규격

  • Url: https://api.pallycon.com/api/v2/pack/[SITE_ID]
  • Method: POST
  • Content type: application/json;charset=UTF-8

트라이얼 시 제약 사항

  1. 트라이얼 계정에서는 Adaptive Streaming 콘텐츠 패키징을 지원하지 않습니다.
  2. 패키징할 원본 영상은 mp4 포맷만 지원됩니다.
  3. 트라이얼 계정은 한 번의 패키징 작업만 제공됩니다.

요청 데이터 JSON 포맷

{
    "job_name": "{job name}",
    "storage":{
        "input":{
            "storage_id": "{storage id}",
            "contents_path":[ input contents path ]
        },
        "output":{
            "storage_id": "{storage id}",
            "path": "{output path}"
        }
    },
    "content_id": "{content id}",
    "streaming_format": [dash, hls],
    "protect_type": [ drm, watermark ],
    "subtitles":[
        {
        "path": "{subtitle path}",
        "language": "{language}"
        }
    ],
    "watermark_option":{
        "gop": "{gop}"
    }
}

요청 데이터 명세

Key type required description
job_name String Y Job 이름
storage JSON Y 콘텐츠가 저장된 스토리지 및 원본 파일 정보
content_id String Y 고객사에서 관리하는 고유한 콘텐츠 ID(CID, 최대 200byte)
streaming_format Array Y 스트리밍 콘텐츠 타입
protection_type Array Y drm, watermark 적용 사항. watermark 는 필수 옵션
subtitles JSON Array N 자막 정보
watermark_option.gop JSON N watermark GOP 값을 설정한다. default : 60

storage.input

Key type required description
storage_id String Y PallyCon에서 발급한 스토리지 고유 ID
contents_path Array Y 원본 파일이 업로드된 폴더/파일 경로. 여러 개가 지정될 경우 Adaptive Streaming 형태로 패키징됨

storage.output

Key type required description
storage_id String Y PallyCon에서 발급한 스토리지 고유 ID
path Array Y 패키징 결과물이 저장될 경로

subtitles

Key type required description
path String N 자막 파일 경로
language String N 자막 파일 언어

응답 규격

응답 데이터 JSON 포맷

{
    "error_code": {error code},
    "error_message": {error message},
    "job_id": {job id}
}

응답 데이터 명세

Key type description
error_code String “0000” : 성공, 에러인 경우 영문/숫자로 정의된 에러코드
error_message String 에러인 경우 에러 메시지
job_id Long Job 등록이 성공한 경우만 발급

패키징 목록 조회 API

PallyCon 패키징 서버에서 패키징 작업 목록를 가져오기 위해서 사용되는 API 입니다.

요청 규격

  • Url : https://api.pallycon.com/api/v2/pack/{siteId}
  • Method : GET
  • Content type : application/json;charset=UTF-8

요청 데이터 JSON 포맷

{
    "search_keyword": "{search keyword}",
    "search_keyword_type": "{cid, jobId, jobname}",
    "search_type": "{watermark, sessionKey}",
    "search_status": "{ready, success, failed, complete, working, process}",
    "search_condition": "{dash, hls}",
    "from": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
    "to": "{YYYY-MM-DD'T'hh:mm:ss'Z'}",
    "page_unit": "{long value}",
    "page_index": "{long value}",
    "time_zone": "{hh:mm}"
}

요청 데이터 명세

Key type required description
from String N 패키징 작업 등록 시간 검색 조건
to String N 패키징 작업 등록 시간 검색 조건
page_unit Int N 검색 갯수. default : 25
page_index Int N 검색 페이지. default : 1
search_type String N 보안 타입 검색(drm, watermark)
search_status String N 진행 상태 검색(ready, success, failed, complete(성공+실패), working(대기+진행), process(진행), stop)
search_condition String N 스트리밍 포멧(dash, hls)
search_keyword_type String N 검색 타입(cid, jobId, jobName)
search_keyword String N 검색어
region String N AWS 리전 코드로 검색
time_zone String N 검색 시간대

응답 규격

응답 데이터 JSON 포맷

{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "total_count": "{count}",
    "time_zone": "{hh:mm}",
    "data": [ {
        "job_id": "{job id}",
        "job_name": "{job name}",
        "start_date": "{start date({YYYY-MM-DD'T'hh:mm:ss'Z')}",
        "update_date": "{update date({YYYY-MM-DD'T'hh:mm:ss'Z')}",
        "reg_date": "{registered date({YYYY-MM-DD'T'hh:mm:ss'Z')}",
        "watermark": "{watermark use}",
        "drm": "{true/false}",
        "dash": "{true/false}",
        "hls": "{true/false}",
        "content_id": "{content id}",
        "status": "{status}",
        "storage":{
            "input":{
                "storage_id": "{storage id}",
                "contents_path":[ input contents path ]
            },
            "output":{
                "storage_id": "{storage id}",
                "path": "{output path}"
            }
        },
        "subtitles":[ {
            "path": "{subtitle path}",
            "language": "{language}"
        } ]
    } ]
}

에러 코드

Code Description
0000 성공
A1000 잘못된 파라미터 값이 입력됨
A1002 Timestamp 형식이 잘못됨
A1003 Site ID를 찾을 수 없음
A1006 해당 사이트 키로 복호화에 실패함
A1007 해시 검증이 실패함
A4002 워터마크 데이터의 저장이 실패함
A4003 워터마크 데이터의 생성이 실패함
A7008 API 데이터 파싱 오류
A7009 API 버전이 맞지 않음