Watermark Detection API Guide
Watermark detection analyzes each frame of the video to detect the original watermark pattern and decrypts the data with the secret key used at the time of insertion. If the watermark payload is found through the detection process, the session database finds the session information whose key value is the payload and reports it as the detection result.
sequenceDiagram
participant A as Service site
participant B as PallyCon service
A ->> B: Suspicious content
Note right of B: Detect watermark (payload)
B -->> B: Analyze video frames
opt Watermark detected
Note right of B: Session database
B -->> B: Find session data
end
B ->> A: Report detection result
Requirements for Detection
The detailed requirements for watermark detection are as follows:
Item | Description |
---|---|
Minimum video length | In order to detect watermarks, continuous recorded video without repeating sections with a length of at least 5 minutes is required |
Video quality | At least 480p with 1Mbps is required for detection. 720p or higher quality recommended |
Video stability | Requires fixed recorded video without shaking. Undetectable if the screen is shaken due to shooting with a handheld camera or smartphone |
Buffering or freezing | There must be a section that was played normally without buffering or screen freezing for at least 5 minutes |
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.
JWT Authorization Specification
You can call the Session API by setting the data issued through the token api in the Authorization
header.
Authentication Token
When calling the Session API, you need to set an authentication token issued by the process below.
Step 1: Generate the base64 encoded Authorization parameter
- Navigate to Base64 Enc/Dec page on PallyCon DevConsole.
- While
Encrypt
option is selected, enter theAccountID:AccessKey
value in the left text field. - Base64 encoded output will be displayed as the screenshot below.
- Copy the output value to use in the next step.
You need to input the
AccountID
andAccessKey
values for your PallyCon service account.
Step 2: Use the parameter value to generate the Authorization token.
Call the token API URL with base64 encoded value in the Authorization
request header.
- URL: https://api.pallycon.com/api/token/[SITE_ID]/
- Method: GET
Path Parameter
Parameter | Format | Description |
---|---|---|
siteId | four alphanumeric characters | Your PallyCon Site ID shown on Console |
Request Header
Name | Description |
---|---|
Authorization | Basic Auth : Basic base64encode(accountId:accessKey) |
Sample Request
GET /api/v2/token/DEMO HTTP/1.1
Authorization: basic authInfo
Host: watermark.pallycon.com
Response Data Fields
Field Name | Type | Info |
---|---|---|
error_code | String | error code |
error_message | String | error message |
data.token | String | api auth token |
Sample Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 112
{
"error_code" : "0000",
"error_message" : "Success.",
"data" : {
"token" : "Bearer valid-token"
}
}
API Request Header
You can call the Session API by setting the data issued through the token api in the authorization header.
Common Response Specifications
Response Status
HTTP Status Code | Description |
---|---|
Error code | Description |
401 | Incorrect JWT Token specification or user information not found |
403 | You do not have permission to use the API. |
200 | Success |
Response Data Fields
Key | type | Value |
---|---|---|
error_code | String | 0000: Success / Other values indicate failure |
error_message | String | Error message |
data | Json | Api result |
Detection request registration API using URL
This API is for requesting a watermark detection using url.
- url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/url
- method : POST
- content type : application/json;charset=UTF-8
Path Varibales
variable | description |
---|---|
SITE_ID | SITE ID |
SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
API Data JSON Format
{
"title": "title",
"file_path": "aaa.mp4",
"demo_contents": false
}
API Data Specification
Key | type | required | description |
---|---|---|---|
title | String | Y | Content title |
file_path | String | Y | Download link for detection target video |
demo_contents | Boolean | N | PallyCon demo contents flag. default: false |
Response Data JSON Format
{
"error_code": "{error code}",
"error_message": "{error message}",
"detection_id": "detection id",
}
Response Data Specification
Key | type | description |
---|---|---|
error_code | String | 0000 : Success, Other codes: Error |
error_message | String | Error message |
detection_id | Number | ID for the detection request generated by PallyCon system |
Signed url issuance API for requesting detection by file upload
A detection request can also be requested by uploading a file directly.
This is an api that issues AWS S3 signed url for file upload.
When uploading a file to the issued url, a detection request is made.
- url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/token
- method : POST
- content type : application/json;charset=UTF-8
Path Varibales
variable | description |
---|---|
SITE_ID | SITE ID |
SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
API Data JSON Format
{
"title": "title"
"file_extension": "mp4",
"demo_contents": false
}
API Data Specification
Key | type | required | description |
---|---|---|---|
title | String | Y | Content title |
file_extension | String | Y | File extension (mp4, mkv, mov) |
demo_contents | Boolean | N | PallyCon demo contents flag. default: false |
Response Data JSON Format
{
"error_code": "{error code}",
"error_message": "{error message}",
"upload_url": "upload url",
}
Response Data Specification
Key | type | description |
---|---|---|
error_code | String | 0000 : Success, Other codes: Error |
error_message | String | Error message |
upload_url | String | Signed url that can be uploaded for 1 minute |
File upload sample (curl)
curl -v --upload-file {filename.mp4} {signed upload url}
Receiving Detection List
This API is for getting watermark detection list and each result.
- url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/list
- method : GET
- content type : application/json;charset=UTF-8
Path Varibales
variable | description |
---|---|
SITE_ID | SITE ID |
SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
API Data JSON Format
{
"search_keyword": "{search keyword}",
"search_condition": "{search condition}",
"detect_status": "FD001",
"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}",
"site_id": "{site id}"
}
API Data Specification
Key | type | required | description |
---|---|---|---|
search_keyword | String | N | Keyword for search condition |
search_condition | String | N | Search condition (title or detection ID). default: title |
detect_status | String | N | Detection status code (FD001 ~ FD005) |
from | String | N | Creation time search condition |
to | String | N | Creation time search condition |
page_unit | Int | N | Number of search items. default : 25 |
page_index | Int | N | Page index. default : 1 |
time_zone | String | N | Time zone |
site_id | String | N | Site id |
Response Data JSON Format
{
"error_code": "{error code}",
"error_message": "{error message}",
"total_count": "total count",
"time_zone": "{hh:mm}",
"data": [{
"detection_id" : "{detection id}",
"site_id" : "{site id}",
"title": "{title}",
"demo_contents": "{demo contents}",
"detect_status" : "{detect status}",
"file_id" : "{file id}",
"file_path": "{file path}",
"region_code": "{region code}",
"service_code": "{service code}",
"wm_key": "{wm key}",
"wm_data": "{wm data}",
"reg_date" : "{register date}",
"update_date": "{update date}"
}]
}
Response Data Specification
Key | type | description |
---|---|---|
error_code | String | 0000 : Success, Other codes: Error |
error_message | String | Error Message |
totla_count | String | totla list count |
time_zone | String | Time Zone |
data.detection_id | Number | Detection ID |
data.site_id | String | Site ID |
data.title | String | Content title |
data.demo_contents | String | PallyCon demo contents flag |
data.file_id | Number | Anti-Piracy: Takedown ID, FWM Service: Detection target file ID |
data.file_path | String | file path |
data.region_code | String | region code |
data.service_code | String | product code(DWM-PD006, FWM-PD002) |
data.wm_key | String | fwm -fwm key, dwm - dwmId |
data.wm_data | String | fwm -fwm data, dwm - recipient |
data.reg_date | String | registration date |
data.update_date | String | update date |
Receiving Detection Detail
This API is for getting watermark detection detail.
- url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/detail
- method : GET
- content type : application/json;charset=UTF-8
Path Varibales
variable | description |
---|---|
SITE_ID | SITE ID |
SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
API Data JSON Format
{
"detection_id": "{detection id}",
"site_id": "{site id}"
}
API Data Specification
Key | type | required | description |
---|---|---|---|
detection id | Number | Y | detection ID |
site_id | String | N | site ID |
Response Data JSON Format
{
"error_code": "{error code}",
"error_message": "{error message}",
"data": {
"detection_id" : "{detection id}",
"site_id" : "{site id}",
"title": "{title}",
"req_type": "{req_ ype}",
"demo_contents": "{demo contents}",
"detect_status" : "{detect status}",
"file_path": "{file path}",
"file_id" : "{file id}",
"service_code": "{service code}",
"wm_key": "{wm key}",
"wm_data": "{wm data}",
"wm_seed_key": "{wm seed key}",
"error_code": "{error code}",
"error_message": "{error message}",
"reg_date" : "{register date}",
"update_date": "{update date}"
}
}
esponse Data Specification
Key | type | description |
---|---|---|
error_code | String | 0000 : Success, Other codes: Error |
error_message | String | Error Message |
data.detection_id | Number | detection ID |
data.site_id | String | Site ID |
data.title | String | Content title |
data.req_type | String | detection request type(url, file) |
data.demo_contents | String | PallyCon demo contents flag |
data.detect_status | String | detection status code(FD001 ~ FD005) |
data.detect_progress_status | String | detection progress status code(FD100 ~ FD700) |
data.file_id | Number | Anti-Piracy: Takedown ID, FWM Service: Detection target file ID |
data.file_path | String | file path |
data.service_code | String | product code(DWM-PD006, FWM-PD002) |
data.wm_key | String | fwm -fwm key, dwm - dwmId |
data.wm_data | String | fwm -fwm data, dwm - recipient |
data.wm_seed_key | String | only ADMIN |
data.reg_date | String | update date |
data.update_date | String | registration date |
data.error_code | String | internal error code |
data.error_message | String | initernal error description |
Request Detection Stop
request detection stop API
- url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/[SERVICE_CODE]/stop
- method : PUT
- content type : application/json;charset=UTF-8
Path Varibales
variable | description |
---|---|
SITE_ID | SITE ID |
SERVICE_CODE | product code in detection service request. FWM - PD002, DWM - PD006. default: PD002 |
API Data JSON Format
{
"detection_id": "{detection id}"
}
API Data Specification
Key | type | required | description |
---|---|---|---|
detection id | Number | Y | detection ID |
Response Data JSON Format
{
"error_code": "{error code}",
"error_message": "{error message}",
"data": "{detection id}"
}
Response Data Specification
Key | type | description |
---|---|---|
error_code | String | 0000 : Success, Other codes: Error |
error_message | String | Error Message |
data | Number | Detetction ID |
Status and Error Codes
Detection Status Codes
Status Code | Description |
---|---|
FD001 | Ready |
FD002 | Downloading |
FD210 | Download started |
FD220 | Download completed |
FD003 | Detecting |
FD311 | Auto-detection started |
FD312 | Auto-detection completed |
FD321 | Manual detection started |
FD322 | Manual detection completed |
FD004 | Completed |
FD400 | Completed (progress) |
FD005 | Detection canceled |
FD510 | Cancel requested |
FD520 | Cancel completed |
FD006 | Error |
FD600 | Error (progress) |
FD700 | Failed (progress) |
Detection Error Codes
Error Code | Description | Cause | Solution |
---|---|---|---|
A1000 | API parameter error | he parameter of the API URL is null or an invalid value was entered. | Follow the API guide and enter the correct parameters to call again. |
A1003 | Site ID value not found | The site ID is missing or an incorrect value was entered in the API parameter. | Check and apply the correct site ID (four-digit alphanumeric) value on the PallyCon Console site. |
A1006 | Site key decryption failed | The data part of pallycon-apidata was encrypted with the wrong site key. |
Check and apply the correct site key value on the PallyCon Console site. |
A1007 | Hash verification failed | The hash value of the API request data was generated incorrectly. | Apply the correct hash value by referring to the API guide document. |
A1108 | Not Service Status | Service is not used. | Request to Service. |
A2022 | Failed to make kafka message | kafka message is not made. | Create a ticket on our Helpdesk to ask for support. |
A2131 | Not Find to DDB | DDB is not connected. | Create a ticket on our Helpdesk to ask for support. |
A2132 | Failed to trial pack count update | Internal server error. | Create a ticket on our Helpdesk to ask for support. |
A4001 | Not support to Service code. | There is no session data stored in our database for the watermark payload. | Create a ticket on our Helpdesk to ask for support. |
A4002 | Failed to register to detect request | Service code is not supported. | Try supported Service code(FWM, DWM) |
A4005 | Required value is invalid : file_path | The filepath parameter in detection request is null or empty string. | Check your detection request and input the missing parameter. |
A4006 | Failed to update detect status | Internal server error. | Create a ticket on our Helpdesk to ask for support. |
A4007 | Failed to register watermark key | Internal server error occurred when PallyCon’s support engineer registers the result of the manual watermark detection. | Create a ticket on our Helpdesk to ask for support. |
A4008 | Failed to send update status notification | Internal server error occurred after updating detection status, failed to send email to user / admin of the detection result. Or failed to send slack messages to PallyCon Channel. | Create a ticket on our Helpdesk to ask for the detection status. |
A4009 | Cannot find detect information | The detect request data is missing due to an internal server error. | Try registering detection request again. If same error arise, create a ticket on our Helpdesk to ask for support. |
A4010 | Cannot find detect key | The detect key is missing due to an internal server error. | Try registering detection request again. If same error arise, create a ticket on our Helpdesk to ask for support. |
A4011 | Failed to send Slack notification message | Failed to send slack messages to PallyCon Channel. | Customers don’t need to do anything about this error. |
A4012 | Failed to update detect info | Internal server error occurred during detecting process. | Create a ticket on our Helpdesk to ask for support. |
A4013 | Failed to send Mail message | Failed to start auto detection process. | Create a ticket on our Helpdesk to ask for support. |
A4015 | Exceed to trial detection count | Max Detection count(2) is exceed in trial. | Try to request trial again. |
A4016 | Failed to get dwmId list | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A4017 | Failed to get max dwm Id | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A4018 | Failed to detection list count | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A4019 | Exceed to detection count | Max Detection count is exceed each service. | Try to reset detection count. |
A4020 | Failed to get detection detail in update | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A4021 | Failed to get detection detail in stop | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A4022 | Failed to get detection detail in download file | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A4023 | Invalid file extension | File Extension(mp4, mpk, mov) is not supported. | Try to check the valid File extension(mp4, mkv, mov) |
A4025 | Updating is not possible with past status values | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A4026 | Fail to access Video File from S3 | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A4027 | Fail to access Log Files from S3 | Internal server error occurred during detecting process | Create a ticket on our Helpdesk to ask for support. |
A7008 | Fail to parsing Pallycon API DATA | pallycon-apidata value is invalid. |
Follow the API guide and enter the correct pallycon-apidata parameters to call again. |
A9001 | Token value is invalid | jwt token value is invalid. |
Enter the basic token format. |
A9002 | Token payload value is invalid | jwt token payload value is invalid. |
|
A9008 | Account information not available | 사용자 게정이 정확하지 않습니다. | Check user information. |
WM900### | Same error message in FWM Packaging Error Code | ||
WM900901, WM900902 | Same error message as WM900903 in FWM Packaging Error Code |
Error Codes for Detection Failure
Error Code | Descriptions |
---|---|
D000 | Etc (undefined detection failure error) |
D001 | Failed to download file. |
D002 | The length of the video is less than 5 minutes. |
D003 | The video codec should be H.264 or H.265. |
D004 | The resolution is below 480P. |
D005 | Bitrate is less than 1 Mbps. |
D006 | Not enough video quality and resolution for watermark detection. |
D007 | The screen is shaking. |
D008 | Too much buffering occurred. |
D009 | The video should not be repeated. |
D010 | The Extension should be in [.mp4, .mkv, .mov] |
D011 | Failed to get the media specification. |
D012 | Invalid key list data. |
D013 | Invalid fwmKey data. |