Packaging API Guide
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' in base64 string}",
"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.
Request Data JSON Format
{
"storage_name" : "{storage name}",
"type" : "{storage type}",
"id": "{access id}",
"password": "{access password}",
"aws_bucket": "{bucket name}",
"description" : "{description}",
"region": "{region}"
}
Request 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
Request Data JSON Format
{
"storage_id" : "{storage id}",
"storage_name" : "{storage name}",
"description": "{description}"
}
Request 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
Request 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}"
}
Request 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.
Request 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}
}
}
Request 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 |
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
Request 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}"
}
Request 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}"
} ]
} ]
}
Packaging Result Callback Numberegration
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>
}
Error Code and Status Code
API error code
Code | Description |
---|---|
0000 | Succeeded |
A1000 | Invalid input parameter |
A1002 | Invalid timestamp format |
A1003 | Cannot find the site ID |
A1006 | Failed to decrypt with the site key |
A1007 | Failed to verify the hash |
A4002 | Failed to store watermark data |
A4003 | Failed to create watermark data |
A7008 | API data parsing error |
A7009 | Invalid API version |
Status code for packaging process
Status code | Status |
---|---|
WM000 | Ready |
WM010 | Get Job LIst |
WM020 | Send Agent |
WM021100 | File downloading |
WM021200 | File download complete |
WM022100 | Watermark packaging |
WM022200 | Watermark packaging complete |
WM023100 | DRM packaging |
WM023200 | DRM packaging complete |
WM023300 | AKAMAI Convert |
WM024100 | File uploading |
WM024200 | File uploading complete |
WM030 | Packaging complete |
WM100 | Request packaging stop |
WM200 | Packaging stop complete |
WM999 | Packaging error |
Error code for packaging process
Error code | Status |
---|---|
WM900101 | Failed to get Job List. |
WM900102 | This Mode does not exist. |
WM900103 | This Mode does not exist. |
WM900104 | Failed to get site information. |
WM900105 | An invalid value from the StoreServer was passed. |
WM900106 | Failed to get CID. |
WM900107 | Failed to get MetaData Information. |
WM900108 | No bucket information or file path. |
WM900109 | Failed to update DB status to SEND_AGENT. |
WM900110 | Failed to update DB status to END. |
WM900111 | Failed to select storage data. |
WM900112 | Failed to get mail form. |
WM900113 | Failed to set Storage information. |
WM900114 | Numberernal cluster error. |
WM900115 | ClusterEvent.UnreachableMember. |
WM900116 | Failed to get pack list. |
WM900117 | Failed to parse Pack Information. |
WM900118 | Failed to update DB status to get pack information. |
WM900119 | Failed to update DB status to cancel job |
WM900120 | Failed to update DB status. |
WM900121 | Job list separate fail. |
WM900122 | Failed to call lambda to stop the instance. |
WM900123 | Failed to make api data. |
WM900124 | Failed to call api. |
WM900125 | Failed to parse api response data. |
WM900126 | Response API error code is not success. |
WM900127 | Watermark status Update Fail to WM010 |
WM900128 | Watermark status Update Fail to WM030 |
WM900129 | Watermark status Update Fail to WM02X |
WM900130 | Watermark status Update Fail to WM200 |
WM900131 | Failed to get stop request list. |
WM900132 | Failed to parse api response data by WM100. |
WM900133 | Watermark status Update Fail to error. |
WM900134 | Job information is null. |
WM900135 | Failed to decrypt pki key. |
WM900136 | Failed to mapping api data to decrypt pki key. |
WM900137 | Failed to create job data. |
WM900001 | Common site key decrypt fail. |
WM900002 | Watermark Job Call API Parameter make fail. |
WM900003 | Watermark Job list API call fail. |
WM900004 | API Return parser fail. |
WM900005 | API error. |
WM900006 | Job Executor error. |
WM900007 | S3 Bucket Access key and id is invalid. |
WM900008 | S3 Bucket connect fail.(key or region is invalid) |
WM900009 | S3 Bucket info is invalid. |
WM900010 | Contents download failed. |
WM900011 | Subtitles download failed. |
WM900012 | S3 get Object failed. |
WM900013 | Download failed.(File does not exist or size is 0kb.) |
WM900014 | The size of the content file is too large. Please switch to commercial. |
WM900015 | Codec is invalid. |
WM900016 | Contents playback time is too short.(At least 12 minutes) |
WM900017 | Video size is invalid.(minimum width 640px) |
WM900018 | Temp file delete failed. |
WM900019 | Upload process failed. |
WM900020 | S3 put object process failed. |
WM900021 | Upload file empty. |
WM900022 | Media info get failed. |