워터마크 검출 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: 검출 결과 리포트

워터마크 검출 요구사항

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

연동 방식

검출 매니져 API 는 2가지 요청 방법을 지원합니다.
Authorization 헤더가 Http Header에 포함되어 있으면 JWT 인증 방식으로 작동합니다.

• pallycon-apidata 연동 (aes 암호화 방식)
• JWT 인증

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 함수에 입력되어야 합니다.

JWT 인증 규격

Authorization 헤더에 토큰 api를 통해 발급된 데이터를 설정하여 검출 API를 호출할 수 있습니다.

JWT Token 발급 API

• JWT 인증 규격을 통한 검출 API 호출 시 아래 과정을 통해 생성한 인증 토큰을 설정해야 합니다.

1단계: Base64 인코딩된 인증 매개변수 생성

1. 웹 브라우저로 PallyCon 데브콘솔의 Base64 Enc/Dec 페이지에 접속합니다.
2. Encrypt 옵션이 선택된 상태에서 AccountID:AccessKey 형태의 값을 왼쪽 필드에 입력합니다.
3. 아래 스크린샷 이미지와 같이 Base64 인코딩 된 값이 화면 오른쪽에 출력됩니다.
4. 다음 단계에서 사용을 위해 출력된 값을 복사해둡니다.

AccountID와 AccessKey 값은 각각 PallyCon 서비스 가입 시 입력한 계정 ID와 가입 후 콘솔에 표시되는 엑세스 키를 입력해야 합니다.

2단계: 인코딩 된 매개변수를 이용해 인증 토큰 생성

1단계에서 생성한 Base64 인코딩 결과 값을 아래 토큰 API 요청의 Authorization 헤더에 설정해 API를 호출합니다.

• URL: https://api.pallycon.com/api/token/[SITE_ID]/
• Method: GET

경로 매개변수

요청 헤더

요청 예제

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

응답 데이터 필드

응답 예제

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 요청 헤더

Authorization 헤더에 토큰 API를 통해 발급된 데이터를 설정하여 세션 매니저 API를 호출할 수 있습니다.

공통 응답 규격

응답 상태

응답 데이터 필드

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

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

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

경로 매개변수

API 데이터 JSON 형식

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

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]/[SERVICE_CODE]/token
• method : POST
• content type : application/json;charset=UTF-8

경로 매개변수

API 데이터 JSON 형식

{
    "title": "title"
    "file_extension": "mp4",
    "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]/[SERVICE_CODE]/list
• method : GET
• content type : application/json;charset=UTF-8

경로 매개변수

API 데이터 JSON 형식

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

응답 데이터 JSON 형식

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

응답 데이터 규격

검출 상세 조회

등록된 검출 요청의 상세 조회 하는 API입니다.

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

경로 매개변수

API 데이터 JSON 형식

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

API 데이터 규격

응답 데이터 JSON 형식

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

응답 데이터 규격

검출 중지 요청

등록된 검출 요청을 중지하는 API입니다.

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

경로 매개변수

API 데이터 JSON 형식

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

API 데이터 규격

응답 데이터 JSON 형식

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

응답 데이터 규격

상태 및 에러 코드

워터마크 검출 상태 코드

워터마크 검출 에러 코드

검출 실패에 대한 에러 코드