Skip to content

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

The detailed requirements for watermark detection are as follows:

ItemDescription
Minimum video lengthIn order to detect watermarks, continuous recorded video without repeating sections with a length of at least 5 minutes is required
Video qualityAt least 480p with 1Mbps is required for detection. 720p or higher quality recommended
Video stabilityRequires fixed recorded video without shaking. Undetectable if the screen is shaken due to shooting with a handheld camera or smartphone
Buffering or freezingThere must be a section that was played normally without buffering or screen freezing for at least 5 minutes

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

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

NameValue
pallycon-apidatabase64 Encoding ( JSON string )
{
"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
dataStringYAES encryption on the JSON string generated by the specification for each API, and the result value is input as a base64 string.
timestampStringYEnter the time of the request at the GMT time zone in “yyyy-mm-ddThh: mm: ssZ” format.
hashStringYEnter 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 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.

You can call the Session API by setting the data issued through the token api in the Authorization header.

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.

ParameterFormatDescription
siteIdfour alphanumeric charactersYour DoveRunner Site ID shown on Console
NameDescription
AuthorizationBasic Auth : Basic base64encode(accountId:accessKey)

Sample Request

GET /api/v2/token/DEMO HTTP/1.1
Authorization: basic authInfo
Host: watermark.pallycon.com
Field NameTypeInfo
error_codeStringerror code
error_messageStringerror message
data.tokenStringapi 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"
}
}

You can call the Session API by setting the data issued through the token api in the authorization header.

Response Status

HTTP Status CodeDescription
Error codeDescription
401Incorrect JWT Token specification or user information not found
403You do not have permission to use the API.
200Success

Response Data Fields

KeytypeValue
error_codeString0000: Success / Other values indicate failure
error_messageStringError message
dataJsonApi result

Detection request registration API using URL

Section titled “Detection request registration API using URL”

This API is for requesting a watermark detection using url.

variabledescription
SITE_IDSITE ID
SERVICE_CODEproduct code in detection service request. FWM - PD002, DWM - PD006. default: PD002
{
"title": "title",
"file_path": "aaa.mp4",
"demo_contents": false
}
Keytyperequireddescription
titleStringYContent title
file_pathStringYDownload link for detection target video
demo_contentsBooleanNDoveRunner demo contents flag. default: false
{
"error_code": "{error code}",
"error_message": "{error message}",
"detection_id": "detection id",
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError message
detection_idNumberID for the detection request generated by DoveRunner system

Detection request registration API using URL (live)

Section titled “Detection request registration API using URL (live)”

This API is for requesting a watermark live detection using url.

variabledescription
SITE_IDSITE ID
SERVICE_CODEproduct code in detection service request. FWM - PD002, DWM - PD006. default: PD002
{
"title": "title",
"file_path": "https://example.cdn.com/live/stream/playlist.m3u8",
"demo_contents": false
}
Keytyperequireddescription
titleStringYContent title
file_pathStringYHLS (.m3u8) live stream manifest URL
demo_contentsBooleanNDoveRunner demo contents flag. default: false
{
"error_code": "{error code}",
"error_message": "{error message}",
"detection_id": "detection id"
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError message
detection_idNumberID for the detection request generated by DoveRunner system

Signed url issuance API for requesting detection by file upload

Section titled “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.

variabledescription
SITE_IDSITE ID
SERVICE_CODEproduct code in detection service request. FWM - PD002, DWM - PD006. default: PD002
{
"title": "title",
"file_extension": "mp4",
"demo_contents": false
}
Keytyperequireddescription
titleStringYContent title
file_extensionStringYFile extension (mp4, mkv, mov)
demo_contentsBooleanNDoveRunner demo contents flag. default: false
{
"error_code": "error code",
"error_message": "error message",
"upload_url": "upload url"
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError message
upload_urlStringSigned url that can be uploaded for 1 minute
curl -v --upload-file {filename.mp4} {signed upload url}

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

variabledescription
SITE_IDSITE ID
SERVICE_CODEproduct code in detection service request. FWM - PD002, DWM - PD006. default: PD002
{
"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}",
"req_types": ["url", "file", "stream"]
}
Keytyperequireddescription
search_keywordStringNKeyword for search condition
search_conditionStringNSearch condition (title or detection ID). default: title
detect_statusStringNDetection status code (FD001 ~ FD005)
fromStringNCreation time search condition
toStringNCreation time search condition
page_unitIntNNumber of search items. default : 25
page_indexIntNPage index. default : 1
time_zoneStringNTime zone
site_idStringNSite id
req_typesArrayNSearch condition (type: url, file, stream)
{
"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}"
}]
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError Message
totla_countStringtotla list count
time_zoneStringTime Zone
data.detection_idNumberDetection ID
data.site_idStringSite ID
data.titleStringContent title
data.demo_contentsStringDoveRunner demo contents flag
data.file_idNumberAnti-Piracy: Takedown ID, FWM Service: Detection target file ID
data.file_pathStringfile path
data.region_codeStringregion code
data.service_codeStringproduct code(DWM-PD006, FWM-PD002)
data.wm_keyStringfwm -fwm key, dwm - dwmId
data.wm_dataStringfwm -fwm data, dwm - recipient
data.reg_dateStringregistration date
data.update_dateStringupdate date

This API is for getting watermark detection detail.

variabledescription
SITE_IDSITE ID
SERVICE_CODEproduct code in detection service request. FWM - PD002, DWM - PD006. default: PD002
{
"detection_id": "{detection id}",
"site_id": "{site id}"
}
Keytyperequireddescription
detection idNumberYdetection ID
site_idStringNsite ID
{
"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}"
}
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError Message
data.detection_idNumberdetection ID
data.site_idStringSite ID
data.titleStringContent title
data.req_typeStringdetection request type(url, file)
data.demo_contentsStringDoveRunner demo contents flag
data.detect_statusStringdetection status code(FD001 ~ FD005)
data.detect_progress_statusStringdetection progress status code(FD100 ~ FD700)
data.file_idNumberAnti-Piracy: Takedown ID, FWM Service: Detection target file ID
data.file_pathStringfile path
data.service_codeStringproduct code(DWM-PD006, FWM-PD002)
data.wm_keyStringfwm -fwm key, dwm - dwmId
data.wm_dataStringfwm -fwm data, dwm - recipient
data.wm_seed_keyStringonly ADMIN
data.reg_dateStringupdate date
data.update_dateStringregistration date
data.error_codeStringinternal error code
data.error_messageStringiniternal error description

request detection stop API

variabledescription
SITE_IDSITE ID
SERVICE_CODEproduct code in detection service request. FWM - PD002, DWM - PD006. default: PD002
{
"detection_id": "{detection id}"
}
Keytyperequireddescription
detection idNumberYdetection ID
{
"error_code": "{error code}",
"error_message": "{error message}",
"data": "{detection id}"
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError Message
dataNumberDetection ID

Configure AWS SNS notifications for session revocation events. This feature allows you to receive automatic notifications when a watermark is detected and sessions need to be revoked.

All Session Revocation Notification APIs use the following path variables:

VariableDescription
SITE_IDYour DoveRunner Site ID (four alphanumeric characters)
NOTI_IDNotification ID (used in detail, update, and delete operations)

Register AWS SNS notification for session revocation events.

{
"noti_name": "my_revoke_notification",
"aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
"aws_access_key": "AKIAEXAMPLEKEY123",
"aws_secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
Keytyperequireddescription
noti_nameStringYNotification name
aws_arnStringYAWS ARN
aws_access_keyStringYAWS access key
aws_secret_keyStringYAWS secret key
{
"error_code": "0000",
"error_message": "Success.",
"data": {
"noti_id": 1
}
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError message
data.noti_idNumberNotification ID

Retrieve all registered notification lists for the site.

{
"error_code": "0000",
"error_message": "Success.",
"data": {
"total_count": 1,
"noti_list": {
"noti_id": 1,
"noti_name": "my_revoke_notification",
"aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
"reg_time": "2025-07-20T09:00:00",
"update_time": "2025-07-21T13:00:00"
}
}
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError message
data.total_countNumberNumber of notifications
data.noti_list.noti_idNumberNotification ID
data.noti_list.noti_nameStringNotification name
data.noti_list.aws_arnStringAWS ARN
data.noti_list.reg_timeStringRegistration date (UTC)
data.noti_list.update_timeStringUpdate date (UTC)

Retrieve details of a specific notification.

{
"error_code": "0000",
"error_message": "Success.",
"data": {
"noti_id": 1,
"noti_name": "my_revoke_notification",
"aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:example-sns",
"reg_time": "2025-07-20T09:00:00",
"update_time": "2025-07-21T13:00:00"
}
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError message
data.noti_idNumberNotification ID
data.noti_nameStringNotification name
data.aws_arnStringAWS ARN
data.reg_timeStringRegistration date (UTC)
data.update_timeStringUpdate date (UTC)

Update an existing notification configuration.

{
"noti_name": "updated_notification",
"aws_arn": "arn:aws:sns:ap-northeast-2:123456789012:updated-sns",
"aws_access_key": "AKIAEXAMPLEKEY456",
"aws_secret_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
Keytyperequireddescription
noti_nameStringNNotification name
aws_arnStringNAWS ARN
aws_access_keyStringNAWS access key
aws_secret_keyStringNAWS secret key
{
"error_code": "0000",
"error_message": "Success.",
"data": {
"noti_id": 1
}
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError message
data.noti_idNumberNotification ID

Delete a registered notification.

{
"error_code": "0000",
"error_message": "Success.",
"data": {
"noti_id": 1
}
}
Keytypedescription
error_codeString0000: Success, Other codes: Error
error_messageStringError message
data.noti_idNumberNotification ID
Status CodeDescription
FD001Ready
FD002Downloading
FD210Download started
FD220Download completed
FD003Detecting
FD311Auto-detection started
FD312Auto-detection completed
FD321Manual detection started
FD322Manual detection completed
FD004Completed
FD400Completed (progress)
FD005Detection canceled
FD510Cancel requested
FD520Cancel completed
FD006Error
FD600Error (progress)
FD700Failed (progress)
Error CodeDescriptionCauseSolution
A1000API parameter errorhe 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.
A1003Site ID value not foundThe 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 DoveRunner Console site.
A1006Site key decryption failedThe data part of pallycon-apidata was encrypted with the wrong site key.Check and apply the correct site key value on the DoveRunner Console site.
A1007Hash verification failedThe hash value of the API request data was generated incorrectly.Apply the correct hash value by referring to the API guide document.
A1108Not Service StatusService is not used.Request to Service.
A2022Failed to make kafka messagekafka message is not made.Create a ticket on our Helpdesk to ask for support.
A2131Not Find to DDBDDB is not connected.Create a ticket on our Helpdesk to ask for support.
A2132Failed to trial pack count updateInternal server error.Create a ticket on our Helpdesk to ask for support.
A4001Not 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.
A4002Failed to register to detect requestService code is not supported.Try supported Service code(FWM, DWM)
A4005Required value is invalid : file_pathThe filepath parameter in detection request is null or empty string.Check your detection request and input the missing parameter.
A4006Failed to update detect statusInternal server error.Create a ticket on our Helpdesk to ask for support.
A4007Failed to register watermark keyInternal server error occurred when DoveRunner’s support engineer registers the result of the manual watermark detection.Create a ticket on our Helpdesk to ask for support.
A4008Failed to send update status notificationInternal 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 DoveRunner Channel.Create a ticket on our Helpdesk to ask for the detection status.
A4009Cannot find detect informationThe 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.
A4010Cannot find detect keyThe 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.
A4011Failed to send Slack notification messageFailed to send slack messages to DoveRunner Channel.Customers don’t need to do anything about this error.
A4012Failed to update detect infoInternal server error occurred during detecting process.Create a ticket on our Helpdesk to ask for support.
A4013Failed to send Mail messageFailed to start auto detection process.Create a ticket on our Helpdesk to ask for support.
A4015Exceed to trial detection countMax Detection count(2) is exceed in trial.Try to request trial again.
A4016Failed to get dwmId listInternal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4017Failed to get max dwm IdInternal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4018Failed to detection list countInternal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4019Exceed to detection countMax Detection count is exceed each service.Try to reset detection count.
A4020Failed to get detection detail in updateInternal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4021Failed to get detection detail in stopInternal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4022Failed to get detection detail in download fileInternal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4023Invalid file extensionFile Extension(mp4, mpk, mov) is not supported.Try to check the valid File extension(mp4, mkv, mov)
A4025Updating is not possible with past status valuesInternal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4026Fail to access Video File from S3Internal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4027Fail to access Log Files from S3Internal server error occurred during detecting processCreate a ticket on our Helpdesk to ask for support.
A4028Job termination failureCannot stop job that is already finishedCheck job status and only request stop for jobs in progress
A4029Session revocation notification duplicate registrationOnly one notification can be registered per siteDelete existing notification before registering new one or modify existing
A4030Invalid AWS SNS ARN registrationInvalid AWS ARN format or not an SNS ARNVerify AWS SNS ARN format (arn:aws:sns:region:account:topic)
A4032AWS SNS connection failureNotification configuration not foundVerify notification ID and site ID, then request with correct information
A4033SNS notification registration failureFailed to connect to AWS SNSCheck AWS credentials, region settings, and network connectivity
A4034SNS notification registration failureInternal server error during notification registrationCreate a ticket on our Helpdesk to ask for support.
A4035SNS notification update failureInternal server error during notification updateCreate a ticket on our Helpdesk to ask for support.
A4036SNS notification deletion failureInternal server error during notification deletionCreate a ticket on our Helpdesk to ask for support.
A7008Fail to parsing Pallycon API DATApallycon-apidata value is invalid.Follow the API guide and enter the correct pallycon-apidata parameters to call again.
A9001Token value is invalidjwt token value is invalid.Enter the basic token format.
A9002Token payload value is invalidjwt token payload value is invalid.
A9008Account information not available사용자 게정이 정확하지 않습니다.Check user information.
Error CodeDescriptions
D000Etc (undefined detection failure error)
D001Failed to download file. 
D002The length of the video is less than 5 minutes.
D003The video codec should be H.264 or H.265.
D004The resolution is below 480P.  
D005Bitrate is less than 1 Mbps. 
D006Not enough video quality and resolution for watermark detection.
D007The screen is shaking. 
D008Too much buffering occurred. 
D009The video should not be repeated. 
D010The Extension should be in [.mp4, .mkv, .mov]
D011Failed to get the media specification.  
D012Invalid key list data.
D013Invalid fwmKey data.