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.

Requesting Watermark Detection

This API is for requesting a watermark detection.

API Data JSON Format

{
    "title": "title"
    "file_path": "aaa.mp4"
}

API Data Specification

Key type required description
title String Y Content title
file_path String Y Download link for detection target video

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

Receiving Detection Results

This API is for getting watermark detection list and each result.

API Data JSON Format

{
    "search_keyword": "{search keyword}",
    "search_condition": "{search condition}",
    "detect_status": "FD001",
    "service_code": "PD002",
    "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}"
}

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)
service_code String N Service code (PD001~)
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

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},
        "vendor_id" : "{site id}",
        "title": "{title}",
        "detect_status" : "{detect status}",
        "file_id" : "{file_id}",
        "service_code": "{service code}",
        "fwm_key": "{fwm key}",
        "fwm_data": "{fwm data}",
        "reg_date" : "{register date}",
     }]
}

Response 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.vendor_id String Site ID
data.title String Content title
data.detect_status String Detection status code (FD001 ~ FD005)
data.file_id Number Anti-Piracy: Takedown ID, FWM Service: Detection target file ID
data.service_code String Product code
data.fwm_key String FWM key
data.fwm_data String Detected watermark data
data.reg_date String Registration date

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
A4001 Failed to find forensicMark information  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 Internal server error caused by invalid request parameters. 1. Check your request parameters.
2. Create a ticket on our Helpdesk to ask for support.
A4003 Failed to register to detect key information 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.
A4004 Cannot find key information same as A4001 Create a ticket on our Helpdesk to ask for support.
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.
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 Queue message Failed to start auto detection process. Create a ticket on our Helpdesk to ask for support.
A4014 Failed to Stop Detection. Internal server error occurred while stopping detection process. Try stopping the detection process again. If same error arise, create a ticket on our Helpdesk to ask for support.
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