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.

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


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}",
    "hash":"{sha256 hash of 'message format' in base64 string}"

Request Data Specification

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