API 문서

AI 이미지 탐지 API

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

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

인증

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

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

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

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

AI 이미지 탐지기

탐지(3단계 프로세스)

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

사전 서명 업로드 URL 받기
이미지 업로드
이미지를 탐지에 제출

1. 사전 서명 업로드 URL 받기

API에서 사전 서명 URL을 요청해 시작합니다. 이 URL로 스토리지 서버에 이미지 파일을 안전하게 업로드할 수 있습니다.

지원 파일 형식

JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF

중요

사전 서명 URL을 요청할 때 이미지 파일 이름에서 공백을 제거해야 합니다.

GET https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg

요청 예시

curl -X GET 'https://detect-image.truthscan.com/get-presigned-url?file_name=example.jpg' \
--header 'apikey: YOUR API KEY GOES HERE'

응답 예시

{
  "status": "success",
  "presigned_url": "https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...",
  "file_path": "uploads/example.jpg"
}

2. 이미지 업로드

제공된 'presigned_url'로 PUT 요청을 통해 이미지를 업로드합니다. 이미지 형식에 맞게 Content-Type을 설정하세요.

중요

업로드 시에도 이미지 파일 이름에서 공백을 제거해야 합니다.

요청 예시

curl -X PUT 'https://image-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.jpg?...' \
  --header 'Content-Type: image/<FILE_FORMAT - jpeg, jpg, png, webp, heic, heif, avif, bmp, tiff, tif>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.jpg' # Attachment

파일 크기 제한

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

업로드 과정에서 파일 형식이 일관되게 유지되는지 확인하세요. 성공 시 상태 코드 200이 반환됩니다.

3. AI 탐지를 위해 이미지 제출

업로드 후 이전 단계의 'file_path'를 참조해 이미지를 AI 탐지에 제출합니다.

POST https://detect-image.truthscan.com/detect

요청 예시

curl -X 'POST' \
  'https://detect-image.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/<FILE_PATH>",
  "generate_preview": false,
  "generate_analysis_details": true
}'

'FILE_PATH'는 첫 단계 '사전 서명 업로드 URL 받기' 응답에서 얻은 경로입니다.

선택 파라미터

generate_preview: 이미지 미리보기 URL 생성 시 'true'(기본: 'false')
document_type: 문서 유형(기본값: 'Image')
email: 처리용 이메일 주소
generate_analysis_details: 심층 AI 분석 결과 활성화 시 'true'(기본: 'false'). 활성화 시 /query 응답에 analysis_results_status 및 analysis_results 필드가 포함됩니다.

응답 예시

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

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

조회

/detect가 반환한 이미지 ID를 받습니다. 이미지 제출 상태와 메타데이터, OCR, ML 모델 분석을 포함한 AI 탐지 전체 결과를 반환합니다.

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

요청 예시

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

응답 예시

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "metadata": [
            "No Information Detected for Real/AI",
            "Could not find anything from ExifTool and Pillow metadata"
        ],
        "metadata_basic_source": "null",
        "ocr": [
            "OCR did not detect AI",
            0.0
        ],
        "ml_model": [
            "AI Generated",
            90.2371538185235
        ],
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "pending",
        "analysis_results": null
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

결과 해석

result: 1~100 점수. 이미지가 AI 생성일 가능성. 높을수록 AI 가능성 높음.
final_result: 전체 판정(예: 'AI Generated', 'Real', 'Digitally Edited', 'AI Edited')
confidence: 탐지 신뢰도 점수
detection_step: 탐지가 완료된 단계. 1=메타데이터만, 2=메타데이터+OCR, 3=메타데이터+OCR+ML(가장 포괄적)
metadata: ExifTool과 Pillow로 추출한 이미지 메타데이터
ocr: 워터마크 탐지를 위한 OCR 분석 결과
ml_model: 머신러닝 모델 결과
preview_url: generate_preview가 true일 때 미리보기 이미지 URL
heatmap_status: 히트맵 생성 상태('pending' 또는 'ready'). 히트맵은 비동기입니다. 처음에는 heatmap_status가 'pending'이고 heatmap_url이 없거나 null일 수 있음. 준비되면 'ready'이고 heatmap_url이 채워짐.
heatmap_url: heatmap_status가 'ready'일 때 히트맵 이미지 URL. 점수 >= 20인 이미지에만 제공.
analysis_results_status: 심층 AI 분석 상태('pending', 'done', 'skipped' 또는 null). 'pending'이면 /query를 계속 폴링 — 백그라운드에서 분석 중. 'done'이면 analysis_results에 완료된 분석. 'skipped', null, 없음이면 이 이미지에 심층 분석 없음.
analysis_results: analysis_results_status가 'done'일 때의 심층 AI 분석 결과. agreement(strong/moderate/weak/disagreement), confidence(0-100), keyIndicators(시각적 이상 배열), detailedReasoning(설명), visualPatterns(스타일 패턴 배열), recommendations(실행 가능 항목) 포함.

중요

히트맵 생성은 비동기입니다. 처음에는 heatmap_status가 'pending'이고 heatmap_url이 없거나 null일 수 있습니다. 준비되면 'ready'이고 heatmap_url이 채워집니다. 점수 >= 20인 이미지에만 히트맵이 생성됩니다.

예: "result": 90.24는 이미지가 AI 생성일 가능성이 높음을 나타냅니다. "final_result": "AI Generated"는 명확한 판정이며 "confidence": 90.24는 높은 신뢰도입니다. "detection_step": 3은 메타데이터, OCR, ML 분석이 모두 완료되었음을 의미합니다. "heatmap_status": "ready"와 "heatmap_url"은 AI 생성으로 탐지된 영역을 보여주는 시각적 히트맵에 접근합니다.

분석 결과(비동기 심층 분석)

/detect 요청에서 'generate_analysis_details'를 'true'로 설정하면 초기 탐지 완료 후 TruthScan이 백그라운드에서 심층 AI 분석을 실행합니다. 첫 /query 응답은 status 'done'과 즉시 사용 가능한 탐지 결과를 반환하지만 analysis_results_status는 여전히 'pending'일 수 있습니다. 초기 결과를 바로 쓰고 심층 분석 완료를 선택적으로 폴링할 수 있습니다.

1. 초기 결과 확정(분석은 아직 대기)

'generate_analysis_details': true로 제출하고 첫 조회에서 status 'done'이면 핵심 탐지 결과(result, final_result, confidence)는 준비됩니다. 하지만 analysis_results_status가 'pending'일 수 있으며 이는 심층 AI 분석이 백그라운드에서 진행 중임을 의미합니다.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "analysis_results_status": "pending",
        "analysis_results": null
    }
}

할 일

초기 탐지 결과(result, final_result, confidence, metadata, ocr, ml_model)를 즉시 사용할 수 있습니다. 심층 분석이 필요하면 동일 이미지 ID로 /query를 계속 폴링해 analysis_results_status가 'pending'에서 바뀔 때까지 확인하세요.

2. 분석 결과를 위해 폴링 유지

동일 이미지 ID로 /query를 계속 호출합니다. 각 응답의 analysis_results_status를 확인합니다. 'pending'에서 'done'으로 바뀌면 analysis_results 객체가 채워집니다.

curl -X 'POST' \
  'https://detect-image.truthscan.com/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769"
}'

3. 분석 완료 — 전체 응답

analysis_results_status가 'done'이면 analysis_results 객체에 합의 수준, 신뢰도, 주요 지표, 상세 추론, 시각 패턴, 권장 사항이 포함된 전체 심층 AI 분석이 들어 있습니다.

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 90.2371538185235,
    "result_details": {
        "is_valid": true,
        "detection_step": 3,
        "final_result": "AI Generated",
        "confidence": 90.2371538185235,
        "heatmap_status": "ready",
        "heatmap_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/uploads/....",
        "analysis_results_status": "done",
        "analysis_results": {
            "agreement": "strong",
            "confidence": 92,
            "keyIndicators": [
                "Unnaturally smooth skin texture",
                "Consistent lighting anomalies"
            ],
            "detailedReasoning": "The image shows clear signs of AI generation with unnaturally smooth textures and consistent lighting patterns not typical of real photography.",
            "visualPatterns": [
                "Uniform noise pattern typical of diffusion models"
            ],
            "recommendations": [
                "Cross-reference with original source if available",
                "Check for metadata inconsistencies",
                "Compare with known AI generation patterns"
            ]
        }
    },
    "preview_url": "https://ai-image-detector-prod.nyc3.digitaloceanspaces.com/previews/..."
}

분석을 사용할 수 없을 때

analysis_results_status가 'skipped', null이거나 없으면 이 이미지에 심층 분석이 생성되지 않습니다. /detect에서 'generate_analysis_details'를 'true'로 설정하지 않았거나 특정 이미지 유형·탐지 시나리오인 경우입니다. 초기 탐지 결과를 최종으로 간주하세요.

{
    "status": "done",
    "result": 12.5,
    "result_details": {
        "analysis_results_status": "skipped",
        "analysis_results": null
    }
}

분석 결과 필드

analysis_results_status: 'pending' = 처리 중, 'done' = 결과 사용 가능, 'skipped' / null / 없음 = 이 이미지에 사용 불가
analysis_results.agreement: 심층 분석이 초기 탐지와 얼마나 일치하는지(strong / moderate / weak / disagreement)
analysis_results.confidence: 심층 분석 신뢰도(0-100)
analysis_results.keyIndicators: 이미지에서 탐지된 구체적 시각적 이상 배열
analysis_results.detailedReasoning: 이 분류 이유에 대한 2~4문장 설명
analysis_results.visualPatterns: 발견된 스타일 패턴 배열(예: 확산 모델 특유의 노이즈 패턴)
analysis_results.recommendations: 추가 검증을 위한 실행 가능한 권장 사항 배열

사용자 크레딧 확인

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

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

요청 예시

curl -X 'GET' \
  'https://detect-image.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
}

헬스 체크

AI 이미지 탐지 서비스 상태를 확인할 수 있습니다.

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

요청 예시

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

응답 예시

{
    "status": "healthy",
    "timestamp": "2024-01-15T10:30:00Z"
}

"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 file format" (400)

원인: 지원하지 않거나 유효하지 않은 이미지 형식

해결:

지원 형식인지 확인(JPG, JPEG, PNG, WebP, JFIF, HEIC, HEIF, AVIF, BMP, TIFF, TIF)
파일이 손상되지 않았는지 확인
업로드 시 Content-Type 헤더 확인

"File too large" (400)

원인: 파일 크기가 10MB 제한 초과

해결:

10MB 미만으로 리사이즈 또는 압축
업로드 전 파일 크기 확인
가능하면 WebP 등 효율적인 형식 사용

처리 문제

"Request timeout" (WebSocket)

원인: 이미지 처리 시간 초과

해결:

더 작거나 단순한 이미지로 시도
서버 부하가 높은지 확인
요청 재시도

문서 상태 "failed"

원인: 다양한 이유로 처리 실패

해결:

이미지가 최소 요건(1KB~10MB)을 충족하는지 확인
지원 형식인지 확인
탐지 제출 전 업로드가 완료되었는지 확인
문제가 지속되면 지원팀에 문의

업로드 문제

"Image upload failed" (403/400)

원인: 유효하지 않거나 만료된 사전 서명 URL 또는 스토리지 서버 문제

해결:

사전 서명 URL은 받은 직후 사용(만료될 수 있음)
이미지 형식에 맞는 Content-Type 확인
업로드 전 파일명에서 공백 제거
만료되었으면 새 사전 서명 URL 생성

"Invalid pre-signed URL" (400)

원인: 파일명에 공백이 있거나 사전 서명 URL이 만료·손상됨

해결:

사전 서명 URL 요청 전 파일명에서 모든 공백 제거
파일명은 영숫자, 하이픈, 밑줄만 사용
필요 시 새 사전 서명 URL 생성

도움이 필요하신가요?

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

문의하기

API 자주 묻는 질문

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