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

For watermark detection, a continuous recorded video of at least 5 minutes or longer is required. PallyCon Forensic Watermark solution is robust against various attacks including resizing, but the actual detection rate of the watermark may vary depending on the video quality (resolution, bitrate, shake, etc.) used for detection. The minimum specification required for detection is 480p 1Mbps or higher, and most of the video over 720p can be detected.

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

  1. Navigate to Base64 Enc/Dec page on PallyCon DevConsole.
  2. While Encrypt option is selected, enter the AccountID:AccessKey value in the left text field.
  3. Base64 encoded output will be displayed as the screenshot below.
  4. Copy the output value to use in the next step.

You need to input the AccountID and AccessKey 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.

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.

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.

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.

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.

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

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. 
Previous