워터마크 검출 API 가이드

워터마크 검출은 영상의 각 프레임을 분석하여 원본 워터마크 패턴을 감지하고 임베딩 시 사용한 비밀 키로 데이터를 해독합니다. 검출 과정을 통해 워터마크 페이로드를 찾아내면, 세션 데이터베이스에서 해당 페이로드를 키 값으로 하는 세션 정보를 찾아 검출 결과로 리포트합니다.

sequenceDiagram
    participant A as 서비스 사이트
    participant B as PallyCon 서비스
    A ->> B: 유출 의심 영상
    Note right of B: 워터마크(페이로드) 검출
    B -->> B: 영상 프레임 분석
    opt 워터마크 검출 시
    Note right of B: 워터마크 세션 데이터베이스
    B -->> B: 해당 세션 정보 검색
    end
    B ->> A: 검출 결과 리포트

워터마크 검출 요구사항

워터마크 검출에 필요한 상세 요구 사항은 다음과 같습니다.

PallyCon HTTP API 규격

PallyCon 서비스에서 사용하는 각종 HTTP API 요청시 아래 규격을 따릅니다.

API 요청 규격에 대한 샘플 코드는 샘플 다운로드 페이지에서 확인하시기 바랍니다.

요청 규격

요청 데이터 JSON 형식

{
    "data":"{각 API 별 `API data` JSON 값을 aes256 cbc 암호화한 base64 문자열}",
    "timestamp":"{yyyy-mm-ddThh:mm:ssZ}",
    "hash":"{아래 'SHA256 입력 형식'의 문자열 값을 sha256 해시 처리한 base64 문자열}"
}

요청 데이터 명세

AES256 암호화

AES256 암호화는 PallyCon Cloud 서비스 사이트 생성 시 발급 되는 Site 키 값을 이용하여 아래와 같이 처리 합니다. ( PallyCon 콘솔 사이트에서 확인 )

• Mode : CBC
• AES key : 32 byte (PallyCon 콘솔 사이트에서 발급 되는 site key)
• AES IV : fixed 16 byte (0123456789abcdef)
• Padding : pkcs7

SHA256 입력 형식

SHA256 해시의 입력값은 다음과 같은 문자열을 조합해 입력합니다.

[site access key] + [site_id] + [json.data] + [json.timestamp]

• site access key: PallyCon Cloud 서비스 사이트 생성 시 발급 되는 access key 값이며 PallyCon 콘솔 사이트에서 확인 가능합니다.
• sha256 해시 함수의 결과 값은 문자열로 변환하지 않고 바이너리 데이터 형태 그대로 base64 함수에 입력되어야 합니다.

Url을 이용한 검출 요청 등록 API

유출이 의심되는 영상에 대해 url을 이용하여 워터마크 검출을 요청하는 API 입니다.

• url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/url
• method : POST
• content type : application/json;charset=UTF-8

API 데이터 JSON 형식

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

API 데이터 규격

응답 데이터 JSON 형식

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

응답 데이터 규격

파일 업로드로 검출 요청을 하기 위한 signed url 발급 API

검출 요청은 직접 파일을 업로드하여 요청할 수도 있습니다. 파일 업로드하기 위한 AWS S3 signed url을 발급하는 api 입니다. 발급받은 url로 파일 업로드 시 검출 요청이 진행 됩니다.

• url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/token
• method : POST
• content type : application/json;charset=UTF-8

API 데이터 JSON 형식

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

API 데이터 규격

응답 데이터 JSON 형식

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

응답 데이터 규격

파일 업로드 샘플 (curl)

curl -v --upload-file {filename.mp4} {signed upload url}

검출 결과 조회

등록된 검출 요청 항목들과 각각의 진행 상황, 검출 결과를 조회하는 API입니다.

• url : https://api.pallycon.com/api/v2/detect/[SITE_ID]/list
• method : GET
• content type : application/json;charset=UTF-8

API 데이터 JSON 형식

{
    "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 데이터 규격

응답 데이터 JSON 형식

{
    "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}",
     }]
}

응답 데이터 규격

상태 및 에러 코드

워터마크 검출 상태 코드

워터마크 검출 에러 코드

검출 실패에 대한 에러 코드