Packaging API Guide
Overview
You can preprocess and package your content using our HTTP-based APIs instead of building a separate server using the CLI Preprocessor or library.
sequenceDiagram
participant A as Service site
participant B as PallyCon cloud
A ->> B: Encoded MP4
B -->> B: Watermark preprocessing
opt Apply Multi-DRM
B -->> B: Content encryption
end
B ->> A: Packaged result
Note right of B: DASH / HLS content<br>(two set with 0, 1 marked)
The packaging storage and job management APIs use the following common specifications:
PallyCon HTTP API Specification
The HTTP API requests used by the PallyCon service follow the specifications below.
Please find the API request sample code in Sample Download page.
Request
Name | Value |
---|---|
pallycon-apidata | base64 Encoding ( JSON string ) |
Request Data JSON Format
{
"data":"{aes256 cbc encryption of 'API data' for each API, and base64 encoding}",
"timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
"hash":"{sha256 hash of 'message format' in base64 string}"
}
Request Data Specification
Name |
Value |
Required |
Description |
---|---|---|---|
data |
String | Y | AES encryption on the JSON string generated by the specification for each API, and the result value is input as a base64 string. |
timestamp |
String | Y | Enter the time of the request at the GMT time zone in “yyyy-mm-ddThh: mm: ssZ” format. |
hash |
String | Y | Enter the hash value generated according to the following specification. |
AES256 Encryption
Aes256 encryption / decryption processing is performed as below using the site key value issued when joining PallyCon service. (Check PallyCon Console site)
- mode : CBC
- AES key : 32 byte (Site key issued from PallyCon Console site)
- AES IV : fixed 16 byte (0123456789abcdef)
- padding : pkcs7
SHA256 message Format
The input value of the SHA256 hash is a combination of the following strings.
[site access key] + [site_id] + [json.data] + [json.timestamp]
- site access key: It is the access key value that is issued when creating PallyConsole Cloud service site. It can be checked on the PallyCon Console page.
- The resulting value of the sha256 hash function must be input to the base64 function as a binary data, not as a string.
Storage Registration API
An API that registers storage used for watermark preprocessing and packaging job. Before you can register a packaging job, you must register the storage that will be used for the job through this API.
Request
- Use PallyCon Cloud HTTP API specification
- URL :
https://api.pallycon.com/api/v2/storage/[SITE_ID]
- Method: POST
- Content type: application/json;charset=UTF-8
The ‘SITE_ID’ part of the URL should be your site ID issued from PallyCon Console site.
API Data JSON Format
{
"storage_name" : "{storage name}",
"type" : "{storage type}",
"id": "{access id}",
"password": "{access password}",
"aws_bucket": "{bucket name}",
"description" : "{description}",
"region": "{region}"
}
API Data Specification
Key | type | required | description |
---|---|---|---|
storage_name | String | Y | Name of the storage |
type | String | Y | Storage type : S3 |
id | String | Y | AWS access key id for the storage |
password | String | Y | AWS secret access key |
aws_bucket | String | Y | Name of S3 bucket |
description | String | N | Description of the storage |
region | String | Y | Storage’s region code |
Response
Response Data JSON Format
{
"storage_id": "{storage id}",
"error_code": "{error code}",
"error_message": "{error message}"
}
Response Data Specification
Key | type | description |
---|---|---|
error_code | String | “0000” : Success, Otherwise it will be alphanumeric error code |
error_message | String | Detailed error message if failed |
storage_id | String | ID of the storage |
Storage Update API
An API that modifies storage information used for watermark preprocessing and packaging operations.
Request
- Use PallyCon Cloud HTTP API specification
- Url:
https://api.pallycon.com/api/v2/storage/[SITE_ID]
- Method: PUT
- Content type: application/json;charset=UTF-8
API Data JSON Format
{
"storage_id" : "{storage id}",
"storage_name" : "{storage name}",
"description": "{description}"
}
API Data Specification
Key | type | required | description |
---|---|---|---|
storage_id | String | Y | Storage ID |
storage_name | String | N | Name of the storage |
description | String | N | Description of the storage |
Response
Response Data JSON Format
{
"storage_id": "{storage id}",
"error_code": "{error code}",
"error_message": "{error message}"
}
Response Data Specification
Key | type | description |
---|---|---|
error_code | String | “0000” : Success, Otherwise it will be alphanumeric error code |
error_message | String | Detailed error message if failed |
storage_id | String | ID of the storage |
Storage List API
An API to get a list of registered storage.
Request
- Use PallyCon Cloud HTTP API specification
- Url :
https://api.pallycon.com/api/v2/storage/[SITE_ID]
- Method : GET
- Content type : application/json;charset=UTF-8
API Data JSON Format
{
"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": "{Number value}",
"page_index": "{Number value}",
"time_zone": "{hh:mm}"
}
API Data Specification
Key | type | required | description |
---|---|---|---|
search_keyword | String | N | keyword of the search |
search_keyword_type | String | N | Type of search (storageId or storageName) |
storage_type | String | Y | Type of storage (S3) |
from | String | N | Search parameter for storage registration time |
to | String | N | Search parameter for storage registration time |
page_unit | Number | N | Number of max result per page. default : 25 |
page_index | Number | N | Index of result page. default : 1 |
region | String | Y | AWS region code |
time_zone | String | N | Timezone for the search |
Response
Response Data JSON Format
{
"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'}"
}]
}
Response Data Specification
Key | type | description |
---|---|---|
error_code | String | “0000” : Success, Otherwise it will be alphanumeric error code |
error_message | String | Detailed error message if failed |
storage_id | String | ID of the storage |
Packaging Job Registration API
This API registers new watermark packaging job. Before you can register a packaging job, you must first register a storage and upload the original MP4 file to that storage.
Request
- Url:
https://api.pallycon.com/api/v2/pack/[SITE_ID]
- Method: POST
- Content type: application/json;charset=UTF-8
Limitations for trial account
- Trial does not support adaptive streaming content packaging.
- The original video to be packaged is only supported in the mp4 format.
- A trial account can perform only one packaging job.
API Data JSON Format
{
"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}"
}
],
"dash_option":{
"min_buffer_time": {Number value},
"enable_average_bandwidth_mpd": {true|false}
},
"drm_option": {
"multi_key": {true|false},
"skip_audio_encryption": {true|false},
"max_sd_height": {Number value},
"max_hd_height": {Number value},
"max_uhd1_height": {Number value},
"clear_lead": {Number value},
"generate_tracktype_manifests": {true|false}
}
}
API Data Specification
Key |
type |
required |
description |
---|---|---|---|
job_name | String | Y | Name of packaging job |
storage | JSON | Y | Storage and file information for the source video |
content_id | String | Y | Unique ID of the content (CID, max 200byte) |
streaming_format | Array | Y | Type of streaming format |
protection_type | Array | Y | Options to apply DRM and watermark. ‘watermark’ is mandatory while ‘DRM’ is optional. |
subtitles | JSON Array | N | Subtitle data, if any. |
dash_option | JSON | N | Options about DASH packaging |
drm_option | JSON | N | Options about DRM encryption |
storage.input
Key |
type |
required |
description |
---|---|---|---|
storage_id | String | Y | ID of the storage assigned by PallyCon. |
contents_path | Array | Y | The folder / file path where the original file is located. If more than one is specified, they are packaged as an adaptive stream |
storage.output
Key | type | required | description |
---|---|---|---|
storage_id | String | Y | ID of the storage assigned by PallyCon. |
path | String | Y | The path where the packaging results will be stored |
subtitles
Key | type | required | description |
---|---|---|---|
path | String | N | Path of the subtitle file |
language | String | N | Language of the subtitle file |
dash_option
Key |
type |
required |
description |
---|---|---|---|
min_buffer_time | Number | N | Specifies, in seconds, a common duration used in the definition of the MPD Representation data rate. Minimum: 2 |
enable_average_bandwidth_mpd | Boolean | N | Use average bandwidth for each track in MPD. default: false |
drm_option
Key |
type |
required |
description |
---|---|---|---|
multi_key | Boolean | N | Enables multi-key packaging. default: false |
skip_audio_encryption | Boolean | N | Disable audio track encryption. default: false(encrypt audio) |
max_sd_height | Number | N | Max resolution to be packaged as SD track. default: 480 |
max_hd_height | Number | N | Max resolution to be packaged as HD track. default: 1080 |
max_uhd1_height | Number | N | Max resolution to be packaged as UHD track. default: 2160 |
clear_lead | Number | N | Unencrypted section at the beginning (by second). default: 0 |
generate_tracktype_manifests | Boolean | N | Create multiple manifest (playlist) files for multi-key packaging. For adaptive streams containing SD to UHD tracks, three manifests are created: ‘SD_ONLY’, ‘SD_HD’, and ‘SD_UHD’. default: false |
If multiple source videos are registered for different resolutions, it can be packaged into adaptive bitrate (ABR) content.
If multiple audio tracks are input in one packaging job, the first track (the top item on the UI) is set as the ‘default audio track’ for the DASH/HLS content to be output.
Response
Response Data JSON Format
{
"error_code": {error code},
"error_message": {error message},
"job_id": {job id}
}
Response Data Specification
Key | type | description |
---|---|---|
error_code | String | “0000” : Success, Otherwise it will be alphanumeric error code |
error_message | String | Detailed error message if failed |
job_id | Number | Returned only on successful job creation |
Packaging Job List API
An API used to retrieve a list of packaging jobs from PallyCon packaging server.
Request
- Url :
https://api.pallycon.com/api/v2/pack/{siteId}
- Method : GET
- Content type : application/json;charset=UTF-8
API Data JSON Format
{
"search_keyword": "{search keyword}",
"search_keyword_type": "{cid, jobId, jobname}",
"search_type": "{watermark, drm}",
"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": "{Number value}",
"page_index": "{Number value}",
"time_zone": "{hh:mm}"
}
API Data Specification
Key |
type |
required |
description |
---|---|---|---|
from | String | N | Search parameter for job registration time |
to | String | N | Search parameter for job registration time |
page_unit | Number | N | Number of max result per page. default : 25 |
page_index | Number | N | Index of result page. default : 1 |
search_type | String | N | Search for security option (drm, watermark) |
search_status | String | N | Search for job status (ready, success, failed, complete(success + failure), working(pending + processing), job progress, stop) |
search_condition | String | N | Streaming format (dash, hls) |
search_keyword_type | String | N | Type of search keyword (cid, jobId, jobName) |
search_keyword | String | N | Search keyword string |
region | String | Y | AWS region code |
time_zone | String | N | Time zone for the search |
Response
Response Data JSON Format
{
"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}"
} ]
} ]
}
Content(track) List API
An API to inquire the list of source tracks included in a specific packaging job, the packaging progress by track, and various other information.
Request
- Url :
https://api.pallycon.com/api/v2/pack/{siteId}/contents
- Method : GET
- Content type : application/json;charset=UTF-8
API Data JSON Format
{
"job_id": "{Packaging job ID}"
}
API Data Specification
Key | type | required | Description |
---|---|---|---|
job_id | String | Y | Packaging job ID |
Response
Response Data JSON Format
{
"error_code": "{error code}",
"error_message": "{error message}",
"total_count": "total count",
"data": [{
"job_id": "{job Id}",
"seq": "{content seq}",
"input_path":"{input file path}",
"status": "{status code}",
"duration": "{duration}",
"content_size": "{content size}",
"width": "{width}",
"height": "{height}",
"fps": "{fps}",
"bitrate": "{bitrate}",
"update_date":"{update date}",
}]
}
Packaging Result Callback Integration
If you set a callback URL for packaging job result on PallyCon Console site, the web page will receive the below request when a job is finished or if there is an error.
Request data JSON
The below JSON data will be sent to the callback URL in POST method without any encryption.
{
"job_id": <job_id>,
"error_code": <error_code>,
"error_message": <error_message>,
"input_contents_path": [<input_contents_path>...],
"output_path": <output_path>
}