검증

검증 API를 사용하면 디지털 콘텐츠에 적용된 워터마크를 검증하고 관련 메타데이터를 추출할 수 있습니다. 이 페이지에서는 워터마크 검증 요청 방법과 결과를 확인하는 방법에 대해 설명합니다.

검증 프로세스

APoT에서 콘텐츠의 워터마크를 검증하는 전체 프로세스는 다음과 같습니다:

파일 업로드 링크 생성을 사용하여 업로드 URL을 받습니다.
받은 URL로 검증할 파일을 업로드합니다.
검증 API를 호출하여 워터마크 검증 작업을 시작합니다.
검증 상태 확인 API를 사용하여 작업 상태와 결과를 확인합니다.

검증 응답 모델

검증 API 응답은 다음과 같은 속성을 포함합니다:

Name
status
Type
string
Description
검증 요청의 상태입니다. 가능한 값: 'pending', 'processing', 'success', 'failed'
Name
requestId
Type
string
Description
검증 요청의 고유 식별자입니다.
Name
fileId
Type
string
Description
검증 대상 파일의 고유 식별자입니다.
Name
result
Type
object
Description
검증 결과를 포함하는 객체입니다. 성공 상태일 때만 제공됩니다.
Name
result.isWatermarked
Type
boolean
Description
파일에 워터마크가 적용되어 있는지 여부입니다.
Name
result.watermarkTypes
Type
array
Description
검출된 워터마크의 유형 목록입니다.
Name
result.metadata
Type
object
Description
워터마크에서 추출한 메타데이터입니다.
Name
result.ipfsLink
Type
string
Description
IPFS에 저장된 메타데이터의 링크입니다(있는 경우).
Name
result.nftInfo
Type
object
Description
NFT 관련 정보입니다(있는 경우).
Name
result.issues
Type
array
Description
검증 과정에서 발견된 이슈 목록입니다.
Name
error
Type
string
Description
검증이 실패한 경우 오류 메시지입니다.

POST/validate

검증 요청하기

이 엔드포인트는 업로드된 파일의 워터마크 검증을 요청합니다. 요청은 비동기적으로 처리되므로 즉시 결과를 반환하지 않습니다.

필수 매개변수

Name
fileId
Type
string
Description
검증할 파일의 고유 식별자입니다. 파일 업로드 API에서 반환된 ID를 사용합니다.

선택적 매개변수

Name
options
Type
object
Description
검증 옵션을 지정합니다.
Name
options.validateTypes
Type
array
Description
검증할 워터마크 유형을 지정합니다. 기본값: ["saforus", "c2pa"]
Name
options.checkNft
Type
boolean
Description
NFT 검증 여부를 지정합니다. 기본값: false
Name
options.checkIpfs
Type
boolean
Description
IPFS 메타데이터 검증 여부를 지정합니다. 기본값: true

요청

POST

/validate

curl -X POST https://api.apot.io/validate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "2ca0b132-cf83-4158-9353-121ff62a351e",
    "options": {
      "validateTypes": ["saforus", "c2pa"],
      "checkNft": true,
      "checkIpfs": true
    }
  }'

응답

{
  "status": "pending",
  "requestId": "f2be4d80-5c4f-42a5-a70b-8e7251cfa8e2",
  "fileId": "2ca0b132-cf83-4158-9353-121ff62a351e"
}

GET/validate/[requestId]

검증 상태 확인하기

이 엔드포인트는 이전에 요청한 검증 작업의 상태를 확인합니다. 검증 작업이 완료되면 워터마크 검증 결과를 반환합니다.

경로 매개변수

Name
requestId
Type
string
Description
확인할 검증 요청의 고유 식별자입니다.

요청

GET

/validate/[requestId]

curl -G https://api.apot.io/validate/f2be4d80-5c4f-42a5-a70b-8e7251cfa8e2 \
  -H "Authorization: Bearer {token}"

응답 (성공)

{
  "status": "success",
  "requestId": "f2be4d80-5c4f-42a5-a70b-8e7251cfa8e2",
  "fileId": "2ca0b132-cf83-4158-9353-121ff62a351e",
  "result": {
    "isWatermarked": true,
    "watermarkTypes": ["saforus", "c2pa"],
    "metadata": {
      "author": "홍길동",
      "creationDate": "2023-03-15",
      "description": "예시 이미지입니다."
    },
    "ipfsLink": "ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq",
    "nftInfo": {
      "tokenId": "12345",
      "contract": "0x1234567890abcdef1234567890abcdef12345678",
      "blockchain": "ethereum",
      "marketplaceUrl": "https://opensea.io/assets/ethereum/0x1234567890abcdef1234567890abcdef12345678/12345"
    },
    "issues": []
  }
}

응답 (워터마크 검출 실패)

{
  "status": "success",
  "requestId": "f2be4d80-5c4f-42a5-a70b-8e7251cfa8e2",
  "fileId": "2ca0b132-cf83-4158-9353-121ff62a351e",
  "result": {
    "isWatermarked": false,
    "watermarkTypes": [],
    "metadata": null,
    "ipfsLink": null,
    "nftInfo": null,
    "issues": [
      {
        "type": "warning",
        "code": "no_watermark_detected",
        "message": "파일에서 워터마크를 찾을 수 없습니다."
      }
    ]
  }
}

응답 (불일치 발견)

{
  "status": "success",
  "requestId": "f2be4d80-5c4f-42a5-a70b-8e7251cfa8e2",
  "fileId": "2ca0b132-cf83-4158-9353-121ff62a351e",
  "result": {
    "isWatermarked": true,
    "watermarkTypes": ["saforus", "c2pa"],
    "metadata": {
      "author": "홍길동",
      "creationDate": "2023-03-15",
      "description": "예시 이미지입니다."
    },
    "ipfsLink": "ipfs://bafybeiemxf5abjwjbikoz4mc3a3dla6ual3jsgpdr4cjr3oz3evfyavhwq",
    "nftInfo": {
      "tokenId": "12345",
      "contract": "0x1234567890abcdef1234567890abcdef12345678",
      "blockchain": "ethereum",
      "marketplaceUrl": "https://opensea.io/assets/ethereum/0x1234567890abcdef1234567890abcdef12345678/12345"
    },
    "issues": [
      {
        "type": "alert",
        "code": "metadata_mismatch",
        "message": "Saforus 워터마크와 C2PA 메타데이터 간에 불일치가 발견되었습니다.",
        "details": {
          "field": "author",
          "saforusValue": "홍길동",
          "c2paValue": "김철수"
        }
      }
    ]
  }
}

응답 (처리 중)

{
  "status": "processing",
  "requestId": "f2be4d80-5c4f-42a5-a70b-8e7251cfa8e2",
  "fileId": "2ca0b132-cf83-4158-9353-121ff62a351e"
}

응답 (실패)

{
  "status": "failed",
  "requestId": "f2be4d80-5c4f-42a5-a70b-8e7251cfa8e2",
  "fileId": "2ca0b132-cf83-4158-9353-121ff62a351e",
  "error": "지원되지 않는 파일 형식입니다."
}

검증 결과 이해하기

APoT의 검증 결과는 다양한 정보를 제공합니다:

워터마크 검출: 파일에 워터마크가 적용되어 있는지 여부와 어떤 유형의 워터마크가 검출되었는지 확인합니다.
메타데이터 추출: 워터마크에서 저자, 생성 날짜, 설명 등의 메타데이터를 추출합니다.
NFT 및 IPFS 정보: 관련 NFT 정보와 IPFS 링크를 제공합니다(있는 경우).
이슈 감지: 다음과 같은 이슈를 감지하고 보고합니다:
- 경고(Warning): 워터마크를 찾지 못한 경우와 같은 경미한 이슈
- 주의(Alert): Saforus 워터마크와 C2PA 메타데이터 간의 불일치와 같은 심각한 이슈
- 위반(Abuse): 위조나 변조 흔적과 같은 심각한 위반 사항

검증 유형

APoT는 다양한 검증 방법을 지원합니다:

Saforus 워터마크 검증: 특수 알고리즘을 사용하여 이미지에 삽입된 보이지 않는 워터마크를 검출합니다.
C2PA 메타데이터 검증: 파일에 포함된 C2PA 메타데이터를 검증하고 추출합니다.
NFT 검증: 블록체인에서 관련 NFT 정보를 검증합니다.
IPFS 메타데이터 검증: IPFS에 저장된 메타데이터를 검증하고 추출합니다.