API 문서

AI 영상 탐지 API

애플리케이션에 TruthScan AI 영상 탐지 API를 통합하기 위한 전체 문서입니다.

코드 없이 FastAPI 엔드포인트에서 직접 테스트해 보세요: https://detect-video.truthscan.com/docs

인증

TruthScan은 API 접근을 위해 API 키를 사용합니다. API 키는 개발자 포털 계정 페이지 상단에 있습니다.

TruthScan은 모든 API 요청에 아래와 같은 형태의 요청 본문에 API 키를 포함할 것을 요구합니다:

{
  "key": "YOUR API KEY GOES HERE"
}

YOUR API KEY GOES HERE를 본인의 API 키로 반드시 바꿔야 합니다.

AI 영상 탐지기

탐지(2단계 프로세스)

AI 영상 탐지 워크플로는 다음 단계로 구성됩니다:

탐지를 위해 영상 제출(multipart 업로드)
작업을 조회해 결과 가져오기

1. 탐지를 위해 영상 제출

영상 파일을 API에 직접 업로드합니다. 서버에서 파일을 검증합니다.

지원 파일 형식

MP4, MOV, AVI, MKV, WEBM

파일 크기 제한

최소 파일 크기: 1KB
최대 파일 크기: 100MB

POST https://detect-video.truthscan.com/detect-file

요청 예시

curl -X POST \
  'https://detect-video.truthscan.com/detect-file' \
  -H 'accept: application/json' \
  -H 'key: YOUR-API-KEY-GOES-HERE' \
  -F 'file=@/path/to/video.mp4;type=video/mp4'

선택 파라미터

document_type: 문서 유형(기본값: 'Video')
email: 처리 알림용 선택 이메일

응답 예시

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

응답에는 탐지 상태 추적을 위한 고유 영상 ID가 포함됩니다.

2. 탐지 상태 및 결과 조회

제출 후 작업 ID로 `/query` 엔드포인트를 폴링하여 상태와 결과를 가져옵니다.

POST https://detect-video.truthscan.com/query

요청 예시

curl -X POST 'https://detect-video.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"id":"JOB-ID-GOES-HERE"}'

응답 예시

{
    "id": "bfd136fc-666b-42d0-89cf-0e9690c98f21",
    "status": "done",
    "result": 0.101969311406719,
    "result_details": {
        "final_stage": "watermark",
        "metadata": {
            "status": "ok",
            "prediction": "no_detection",
            "confidence": 0.0
        },
        "watermark": {
            "prediction": "ai_generated (watermark)",
            "confidence": 1.0
        },
        "ml": {
            "aggregate": {
                "prob_fake": 0.1019693114067195,
                "label": "cancelled",
                "n_frames": 256,
                "latency_sec": 23.319
            }
        },
        "latency_sec": 24.017
    },
    "preview_url": null
}

결과 상세

status: "pending", "analyzing", "done", "failed" 중 하나
result: ML prob_fake에서 도출한 [0.0, 1.0] 스칼라 점수
final_stage: 결과에 기여한 마지막 단계: 'metadata', 'watermark', 'ml'
metadata: 항상 prediction: 'no_detection', confidence: 0.0. status는 'reject', 'reencode', 'ok' 중 하나
watermark: 프레임을 샘플링하고 픽셀 분산으로 의사 신뢰도를 계산하는 휴리스틱
ml: 샘플 프레임에 분류기 모델 실행. prob_fake [0.0, 1.0] 및 label('ai_generated' if prob_fake ≥ 0.5, else 'no_detection') 반환
latency_sec: 전체 파이프라인 소요 시간(초)

`status` 필드는 "pending"(대기), "analyzing"(AI 탐지 진행 중), "done"(결과 사용 가능), "failed"(처리 실패) 중 하나입니다.

사용자 크레딧 확인

이 엔드포인트는 헤더로 사용자 apikey를 받아 크레딧 정보를 반환합니다.

GET https://detect-video.truthscan.com/check-user-credits

요청 예시

curl -X 'GET' \
  'https://detect-video.truthscan.com/check-user-credits' \
  -H 'apikey: YOUR API KEY GOES HERE' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

응답 예시

{
    "baseCredits": 10000,
    "boostCredits": 1000,
    "credits": 11000
}

헬스 체크

API 서버의 상태를 확인합니다.

GET https://detect-video.truthscan.com/health

요청 예시

curl -X 'GET' \
  'https://detect-video.truthscan.com/health' \
  -H 'accept: application/json'

응답 예시

{
    "status": "healthy"
}

오류

대부분의 오류는 API에 잘못된 파라미터를 보낼 때 발생합니다. 각 호출의 파라미터 형식을 다시 확인하고 예제 코드를 실행해 보세요.

사용하는 일반 오류 코드는 REST 표준을 따릅니다:

오류 코드	의미
400	Bad Request -- 요청이 유효하지 않습니다.
403	Forbidden -- API 키가 유효하지 않거나 영상 처리에 크레딧이 부족합니다.
404	Not Found -- 지정한 리소스가 없습니다.
405	Method Not Allowed -- 잘못된 메서드로 리소스에 접근했습니다.
406	Not Acceptable -- JSON이 아닌 형식을 요청했습니다.
410	Gone -- 이 엔드포인트의 리소스가 제거되었습니다.
422	Invalid Request Body -- 요청 본문 형식이 잘못되었거나 유효하지 않거나 필수 파라미터가 누락되었습니다.
429	Too Many Requests -- 요청이 너무 많습니다. 속도를 줄이세요.
500	Internal Server Error -- 서버 오류가 발생했습니다. 나중에 다시 시도하세요.
503	Service Unavailable -- 유지보수로 일시 중단되었습니다. 나중에 다시 시도하세요.

자주 발생하는 문제와 해결

인증 문제

"User verification failed" (403)

원인: API 키가 잘못되었거나 만료됨

해결:

API 키가 정확한지 확인
계정에서 API 키가 활성인지 확인
API 키 재발급 시도

"Not enough credits" (403)

원인: 영상 처리에 크레딧 부족

해결:

/check-user-credits로 남은 크레딧 확인
필요 시 추가 크레딧 구매

입력 검증 문제

"Unsupported video type" (400)

원인: 지원하지 않는 파일 형식

해결:

지원 형식(MP4, MOV, AVI, MKV, WEBM)으로 변환
확장자와 MIME 타입이 일치하는지 확인

"File size exceeds limit" (400)

원인: 영상 파일이 너무 큼

해결:

압축·트리밍·재인코딩으로 크기를 줄임(최대 100MB)
더 효율적인 코덱/컨테이너 사용

"File size is too small" (400)

원인: 최소 크기 미만

해결:

더 큰 영상 파일 사용(최소 1KB)
업로드 중 파일 손상 여부 확인

"Invalid file type" (400)

원인: 파일 유형 검증 실패(예: MIME 불일치 또는 손상된 파일)

해결:

유효한 영상 형식인지 확인
MIME 확장자와 일치하는지 확인
필요 시 파일을 다시 내보내거나 재인코딩

처리 문제

영상 상태 "failed"

원인: 처리 실패(예: 컨테이너 읽기 불가, 디코드 오류)

해결:

일반적으로 지원되는 컨테이너/코덱 사용 권장(MP4의 H.264/AAC 등)
표준 프리셋으로 재인코딩(예: ffmpeg) 후 재업로드
형식·크기 요건 충족 여부 확인

영상 상태 "timeout" 또는 장시간 처리

원인: 처리가 예상보다 오래 걸리거나 타임아웃됨

해결:

잠시 후 `/query`로 상태 재확인
형식·크기 요건 충족 여부 확인
문제가 지속되면 지원팀에 문의

"User not found"

원인: 잘못된 사용자 ID

해결:

API 키가 정확하고 활성 계정과 연결되어 있는지 확인
연동 사용자가 유효하고 활성인지 확인
필요 시 재인증

"File metadata could not be fetched" (500)

원인: 업로드 파일에 접근하거나 파싱할 수 없음

해결:

업로드가 정상 완료되었는지 확인
파일 접근 가능·손상 없음 확인
파일 재업로드 시도

도움이 필요하신가요?

API 사용 또는 기술 지원이 필요하면 문의해 주세요.

문의하기

API 자주 묻는 질문

AI 영상 탐지 API에 대한 가장 흔한 질문과 답변입니다.