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 DoveRunner 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:

DoveRunner HTTP API Specification

The HTTP API requests used by the DoveRunner service follow the specifications below.

Please find the API request sample code in Sample Download page.

Request

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

AES256 Encryption

Aes256 encryption / decryption processing is performed as below using the site key value issued when joining DoveRunner service. (Check DoveRunner Console site)

• mode : CBC
• AES key : 32 byte (Site key issued from DoveRunner 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 DoveRunner cloud service site. It can be checked on the DoveRunner 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 DoveRunner 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 DoveRunner 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

Request Header

Sample Request

GET /api/v2/token/DEMO HTTP/1.1
Authorization: basic authInfo
Host: watermark.pallycon.com

Response Data Fields

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

Response Data Fields

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

API Data JSON Format

{
  "title": "title",
  "file_path": "aaa.mp4",
  "demo_contents": false
}

API Data Specification

Response Data JSON Format

{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "detection_id": "detection id",
}

Response Data Specification

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

API Data JSON Format

{
    "title": "title"
    "file_extension": "mp4",
    "demo_contents": false
}

API Data Specification

Response Data JSON Format

{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "upload_url": "upload url",
}

Response Data Specification

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

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

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

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

API Data JSON Format

{
    "detection_id": "{detection id}",
    "site_id": "{site id}"
}

API Data Specification

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

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

API Data JSON Format

{
    "detection_id": "{detection id}"
}

API Data Specification

Response Data JSON Format

{
    "error_code": "{error code}",
    "error_message": "{error message}",
    "data": "{detection id}"
}

Response Data Specification

Status and Error Codes

Detection Status Codes

Detection Error Codes

Error Codes for Detection Failure