Deepfake Detection API: 플랫폼에 이미지 및 비디오 검증 추가하기

플랫폼에서 사용자가 업로드한 이미지를 받거나 동영상을 받는다면, 합성 미디어(synthetic media)는 이미 여러분의 파이프라인 안에 존재합니다. 프로필 사진, 온보딩 과정 중 ID 셀카, 제품 목록 이미지, 뉴스룸에 제출된 UGC 클립, 비디오 추천사 등이 해당됩니다. 그중 일부가 생성되거나 조작되었으며, 이 비율은 증가하고 있습니다.

본 가이드는 DeepfakeDetector.ai API를 사용하여 탐지 기능을 추가하는 방법을 다룹니다: 키 받기, 이미지 스캔하기, 동영상 비동기 처리(asynchronously)하기, 응답을 방어적으로 파싱(parsing defensively)하기, 그리고 대부분의 가이드가 건너뛰는 부분인 결과를 사실(fact)이 아닌 확률(probability)로 기반하여 제품을 설계하는 방법입니다.

API 기능 소개
API 키 받기
첫 번째 요청: URL로 이미지 전송하기
파일 업로드하기
응답 읽기
동영상: 동기(sync), 비동기(async) 및 웹훅(webhooks)
프로덕션 레디 래퍼(wrapper)
확률적 판결을 기반으로 설계하기
개인정보 보호 및 데이터 처리
속도 제한, 가격 책정 및 비용 제어
통합 패턴
FAQ

1. API 기능 소개

DeepfakeDetector.ai API는 이미지, 동영상 또는 음성 파일을 받아 그것이 AI가 생성했거나 조작되었는지에 대한 판결(verdict), 신뢰 점수(confidence score), 그리고 그 근거가 된 신호(signals)를 반환합니다.

모든 것은 하나의 기본 URL 뒤에 위치하며, 미디어 유형 전반에 걸쳐 동일한 인증 방식(auth), 응답 형태(response shape), 오류 의미론(error semantics)을 가집니다:

일반적인 지연 시간과 함께 문서에서 나열된 엔드포인트는 다음과 같습니다:

POST /api/v1/detect/image: 약 0.8초 소요
POST /api/v1/detect/video: 짧은 클립의 경우 약 2.1초 소요
POST /api/v1/detect/voice: 약 1.4초 소요
GET /api/v1/jobs/{id}: 비동기 작업 확인용으로 약 50밀리초 소요

이미지의 경우 Midjourney, DALL·E, Stable Diffusion, Flux를 포함한 주요 생성기에서 만든 AI 이미지와 얼굴을 탐지합니다. 비디오의 경우 얼굴 교체(face swaps), 립싱크 조작(lip-sync manipulation), 그리고 완전히 AI가 생성한 클립을 프레임별로 분석하여 다룹니다. 이 가이드는 이미지와 비디오에 초점을 맞추며, 음성(voice)은 자체 엔드포인트를 통해 동일하게 작동합니다.

2. API 키 받기

API 접근은 Starter 플랜부터 시작됩니다. 무료 티어는 웹 앱에서 월 50개의 탐지 건을 제공하여 유료 결제 전에 자체 미디어의 정확도를 평가하는 데 유용하지만, API 접근은 포함되어 있지 않습니다.

키는 한 번만 표시됩니다. DeepfakeDetector.ai는 저장된 키를 해시화하며 생성 시에만 전체 키를 표시합니다. 즉시 비밀 관리자(secrets manager)에 복사해 두세요.

서버 측에서 유지하세요. 요청은 Bearer 토큰으로 인증되며, 브라우저 번들에 있는 키는 누구나 읽을 수 있는 키입니다. 아래의 모든 호출은 백엔드에 위치해야 합니다.

export DFD_API_KEY="sk_live_..."

3. 첫 번째 요청: URL로 이미지 전송하기

가장 간단한 호출은 공개적으로 접근 가능한 HTTPS URL을 전달하는 것입니다:

curl -X POST https://app.deepfakedetector.ai/api/v1/detect/image \
  -H "Authorization: Bearer $DFD_API_KEY" \
  -H "Content-Type: application/json" \
...

이 요청은 처음부터 알아두면 좋은 몇 가지 선택적 매개변수를 허용합니다:

media_type: image, video, 또는 voice. 생략할 경우 MIME 타입에서 추론됩니다.
strict_mode: 신뢰도 임계값(confidence threshold)을 낮추어 더 많은 합성 미디어를 포착하지만, 오탐지율(false positives)이 높아질 수 있습니다. 기본값은 false입니다.
callback_url: 비동기 작업용 웹훅(webhook)으로, 섹션 6에서 다룹니다.
retain: 감사 목적으로 파일을 30일 동안 보관합니다. 기본값은 false이며, 이 경우 판결(verdict) 후 60초가 지나면 파일이 삭제됩니다.

만약 미디어가 사설 스토리지에 있는 경우, 짧은 만료 기한을 가진 서명된 URL(signed URL)이 잘 작동합니다. API가 파일을 가져가고 링크는 곧 만료되기 때문입니다.

4. 파일 업로드하기 대신

4. URL 대신 파일 직접 전송하기

URL이 아닌 파일을 가지고 있는 경우, multipart form data로 전송하세요:

curl -X POST https://app.deepfakedetector.ai/api/v1/detect/image \
  -H "Authorization: Bearer $DFD_API_KEY" \
  -F "file=@./uploads/selfie.jpg"

media_url 또는 multipart 업로드 중 하나만 필요하며, 둘 다 필요한 것은 아닙니다.

지원되는 형식에는 비디오의 경우 MP4, MOV, WEBM이 포함되며, 이미지의 경우 JPG, PNG, WEBP가 포함되고 일반적인 오디오 형식도 지원됩니다. 파일 크기 및 지속 시간 제한은 사용하시는 플랜에 따라 달라지며, 유료 플랜의 경우 감지당 최대 10분 길이의 비디오를 처리할 수 있습니다.

사용자 업로드와 관련한 실용적인 조언: 파일을 저장하기 위해 트랜스코딩(transcode), 크기 조정(resize) 또는 압축하기 전에 사용자가 실제로 제출한 원본 파일을 스캔하세요. 재인코딩은 탐지기가 의존하는 아티팩트(artifacts)를 저하시킬 수 있으며, 문서에는 심한 압축이 결과가 불분명할 수 있는 일반적인 이유라고 명시되어 있습니다.

5. 응답 읽기

완료된 감지는 구조화된 JSON을 반환합니다. API 문서의 예시는 다음과 같습니다:

{
  "job_id": "job_8mTk2x",
  "verdict": "synthetic",
...
}

각 필드가 제공하는 정보는 다음과 같습니다:

verdict와 confidence: 이 두 가지가 대부분의 로직을 구성하게 됩니다. Confidence는 0과 1 사이의 부동 소수점(float) 값입니다.

signals: 감지 결과로 이어지는 원인을 설명하며, 이것이 플래그 검토를 불투명한 것보다 검토 가능하도록 만듭니다.

generator_family: 예상되는 생성기(generator)의 유형을 나타내며, 예를 들어 확산 기반(diffusion-based)일 수 있습니다.

flagged_segments: 비디오 및 음성에 적용되며, 실패한 부분에 대한 시작 시간과 끝 시간을 초 단위로 제공합니다. 비디오 중재(moderation)의 경우 이 필드가 응답에서 가장 유용합니다. 검토자가 전체 클립을 시청하는 대신 2.4초 지점으로 바로 이동할 수 있습니다.

job_id: 요청을 식별합니다. 나중에 특정 감지 결과에 대한 결정을 추적하려면 모든 결과와 함께 이를 저장해야 합니다.

한 가지 심각하게 고려해야 할 주의사항이 있습니다. DeepfakeDetector.ai의 웹 앱은 판결을 'Authentic', 'Likely Synthetic', 또는 'Inconclusive'로, 그리고 0부터 100까지의 TrustScore와 함께 제시하며, 자체 페이지에 있는 예시들은 동일한 필드 이름과 판결 문자열을 사용하지 않습니다. 정확한 판결 값을 일치시키는 로직을 작성하기 전에, 최신 API 문서를 통해 현재 enum(열거형)을 확인하고, 단순히 문자열 매칭보다는 confidence를 기반으로 임계값을 설정해야 합니다. 섹션 7의 래퍼가 바로 이 작업을 수행합니다.

6. 비디오: 동기식(sync), 비동기식(async), 및 웹훅(webhooks)

이미지와 짧은 클립은 빠르게 반환됩니다. 비디오 처리는 지속 시간에 따라 실시간에 가깝게 확장되므로, 3분짜리 클립은 약 3분이 걸립니다. 그렇게 오랫동안 HTTP 요청을 열어두는 것은 좋지 않은 방법이며, API가 이를 방지하도록 설계되었습니다.

60초가 넘는 파일의 경우, 웹훅을 사용하세요. callback_url을 전달하면 분석이 완료될 때 API가 해당 URL로 판결 결과를 POST합니다:

curl -X POST https://app.deepfakedetector.ai/api/v1/detect/video \
  -H "Authorization: Bearer $DFD_API_KEY" \
  -H "Content-Type: application/json" \
...

즉시 job_id를 받게 됩니다. 이 ID를 해당 레코드와 함께 저장하세요.

웹훅을 진실이 아닌 알림으로 취급하세요. 공식 SDK가 웹훅 서명 검증(signature verification)을 대신 처리해 줍니다. API를 직접 호출하는 경우, 가장 간단하고 견고한 패턴은 웹훅을 트리거로만 사용하고, 권위 있는 결과를 직접 가져오는 것입니다:

GET https://app.deepfakedetector.ai/api/v1/jobs/{job_id}

이렇게 하면 귀하의 웹훅 엔드포인트로 위조된 POST가 들어와도, 귀하가 실행한 인증된 호출에서 항상 결과가 나오기 때문에 시스템에 가짜 판결을 밀어 넣을 수 없습니다.

정산 스윕(reconciliation sweep)을 추가하세요. 웹훅은 간혹 도착하지 않을 때가 있습니다. 적절한 시간 창이 지난 후에도 아직 보류 중인 감지 항목을 동일한 jobs 엔드포인트를 사용하여 확인하는 예약 작업이 이러한 공백을 메워줍니다.

7. 프로덕션 레디(production-ready) 래퍼

여기서는 타임아웃(timeout), 속도 제한(rate limits) 처리 및 섹션 5에서 언급된 판정 결과 정규화(verdict normalization)를 처리하는 Node wrapper가 있습니다:

const BASE = "https://app.deepfakedetector.ai/api/v1";

async function detectMedia(mediaUrl, { type = "image", callbackUrl, timeoutMs = 15000 } = {}) {
...

data.job_id ?? data.id의 폴백(fallback)은 섹션 5에서 언급된 필드 이름의 변화를 고려할 때 의도적인 것입니다. 라이브 스키마(live schema)가 확정되면 이 부분을 더 간결하게 만들 수 있습니다.

지수 백오프(exponential backoff)를 적용한 Python 버전은 다음과 같습니다:

import os
import time
import requests
...

만약 직접 코드를 작성하기 어렵다면, DeepfakeDetector.ai에서 공식 SDK를 제공합니다. 이 SDK는 인증(auth), 재시도(retries), 백오프, 파일 스트리밍, 웹훅 서명 검증 등을 처리해 줍니다. API 페이지에는 JavaScript 및 TypeScript, Python, Go, Ruby, PHP, Java, .NET, Rust용 클라이언트가 나열되어 있습니다.

8. 확률적 판정 결과(probabilistic verdict)를 중심으로 설계하기

이 부분이 통합 시스템의 성공과 실패를 가르는 지점입니다. DeepfakeDetector.ai는 자체 탐지 기능을 절대적인 것이 아닌 확률적인 것으로 설명하며, 귀하의 제품도 이를 반영해야 합니다.

두 가지 결과가 아닌 세 가지 결과를 사용하세요. 이진(binary) 방식의 통과 또는 차단은 모든 불확실한 결과를 잘못된 범주에 넣게 만듭니다. 계층적 설계(tiered design)는 중간 지점에 머무를 곳을 제공합니다:

function triage(result) {
  if (result.pending) return "awaiting_result";
  if (result.confidence < 0.5) return "clear";
...

이 함수는 참고 자료일 뿐, 권장 사항은 아닙니다. 경계를 어디에 설정할지는 귀하의 제품에서 오류가 초래하는 비용에 달려 있으며, 실제 미디어 샘플을 사용하여 이 경계들을 조정해야 합니다.

오류 비용이 더 큰 strict_mode를 선택하세요. 이는 재현율(recall)을 높이고 정밀도(precision)를 낮춥니다. 합성된 ID가 누락되는 것이 값비싼 KYC 온보딩(KYC onboarding)의 경우, 엄격 모드(strict mode)가 적절합니다. 반면, 실제 사용자를 잘못 플래그 지정하여 신뢰도를 손상시키는 소셜 피드의 경우에는 기본 설정(default)이 보통 더 좋습니다.

결정하기 어려운 결과는 담당자에게 전달하여 더 나은 입력을 요청하세요. 과도한 압축(Heavy compression)은 낮은 신뢰도의 흔한 원인입니다. 원본 파일이나 고화질 사본을 요청하면 종종 해결됩니다.

점수만으로 결정을 자동화하지 마세요. 계정 차단, ID 거부 또는 사용자 콘텐츠를 가짜로 라벨링하는 것은 검토 과정을 거쳐야 하며, 특히 판정이 임계값(threshold) 근처에 있을 때는 더욱 그렇습니다.

가능한 한 여러 신호를 조합하세요. 탐지 결과는 존재할 경우 Content Credentials와 같은 출처 확인(provenance checks), 계정 기록, 업로드 맥락과 함께 가장 강력합니다.

9. 개인 정보 보호 및 데이터 처리 (Privacy and data handling)

사용자 미디어를 처리하는 경우, 정확도만큼이나 데이터 처리 기본 설정(data handling defaults)이 중요하며, 여기서는 합리적입니다.

파일은 기본적으로 판정 후 60초 뒤에 삭제됩니다. retain: true로 설정하면 파일을 30일 동안 보관하므로, 규제된 워크플로우의 감사 추적(audit trails)에 유용합니다. 특별한 이유가 없다면 이 설정을 비활성화 상태로 두세요.

키는 저장 시 해시 처리되며, 모든 호출은 감사를 위해 요청 ID를 반환합니다.

EU 데이터 거주지(data residency) 기능은 Business 플랜 이상에서 이용 가능합니다.

SOC 2는 진행 중이며, 완료된 상태가 아닙니다. 회사는 이를 명확히 밝히고 있으며, 인증을 가정하기보다는 자체 규정 준수 팀과 똑같이 명확하게 소통할 가치가 있습니다.

10. 호출 제한(Rate limits), 가격 책정 및 비용 제어 (Pricing and cost control)

호출 제한은 플랜에 따라 분당 60회에서 300회까지이며, 알려진 클라이언트에게는 버스트 허용량(burst allowance)이 제공됩니다. 이 API는 status.deepfakedetector.ai의 상태 페이지를 통해 99.9% 가동 시간 SLO(Service Level Objective)를 목표로 합니다.

API 접근 플랜:

Starter: 월 $49, 탐지 횟수 1,000회
Business: 월 $199, 탐지 횟수 5,000회
Enterprise: 월 $599, 탐지 횟수 20,000회

연간 결제 시 최대 20%를 절약할 수 있습니다. 월별 탐지 횟수는 웹 앱과 API 간에 공유되므로, 둘 다 사용하는 팀은 하나의 풀(pool)에서 사용합니다.

다음 습관들을 통해 사용량을 통제할 수 있습니다:

합성될 수 없는 것은 검사하지 마세요. 시스템에서 생성된 썸네일, 자체 마케팅 에셋, 신뢰할 수 있는 내부 출처의 미디어는 검사가 필요 없습니다.

중복 제거를 하세요. 동일한 밈(meme)이나 스톡 사진이 수천 번 도착할 수 있으므로, 업로드된 파일에 해시(Hash) 값을 지정하고 결과를 캐싱하세요.

결정 지점에서 검사하세요. 모든 조회 시가 아니라, 온보딩(onboarding) 시, 게시(publication) 시, 지급(payout) 시 등 미디어가 중요해지기 직전에 검사하세요.

11. 통합 패턴 (Integration patterns)

The API는 상당히 다른 제품에 적용될 수 있습니다.

KYC 및 신원 확인. 계정이 승인되기 전에 온보딩 시 셀카와 ID 이미지를 검사합니다. 이 경우 엄격 모드(strict mode)와 필수 검토 단계가 빛을 발합니다.

신뢰 및 안전 (Trust and safety). 공개 피드에 도달하기 전에 업로드된 이미지와 비디오를 스크리닝하고, 플래그가 지정된 항목은 flagged_segments가 첨부된 중재(moderation) 대기열로 라우팅하여 중재자가 관련 몇 초만 검토할 수 있도록 합니다.

뉴스룸 및 팩트 체크. 게시 전에 사용자 제출 영상을 검증하며, 무엇을 언제 검사했는지 감사 기록이 필요하다면 retain: true를 사용합니다.

마켓플레이스. 생성된 이미지가 재고나 신원을 위조하는 데 사용되는 경우에 대비하여 목록 사진과 판매자 인증 이미지를 검사하세요.

금융 사기 예방. 지급을 요청하는 음성 메시지 및 비디오 통화를 검증하며, 금융 팀을 대상으로 하는 사칭 시도를 위해 영상과 함께 음성 엔드포인트(voice endpoint)를 사용합니다.