API 문서

AI 오디오 탐지 API

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

코드 없이 FastAPI 엔드포인트에서 직접 테스트해 보세요: https://detect-audio.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로 스토리지 서버에 오디오 파일을 안전하게 업로드할 수 있습니다.

지원 파일 형식

MP3, WAV, M4A, FLAC, OGG, MP4

중요

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

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

요청 예시

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

응답 예시

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

2. 오디오 업로드

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

중요

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

요청 예시

curl -X PUT 'https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg, mp4>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

파일 크기 제한

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

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

3. AI 탐지를 위해 오디오 제출

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

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

요청 예시

curl -X 'POST' \
  'https://detect-audio.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'

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

선택 파라미터

analyzeUpToSeconds: 처음부터 최대 N초 분석(기본: 60)
document_type: 문서 유형(기본값: 'Audio')
email: 처리 알림용 선택 이메일

응답 예시

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

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

탐지 상태 및 결과 조회

상태 확인 및 결과를 가져오려면 ID로 /query 엔드포인트를 사용하세요.

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

요청 예시

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

응답 예시

{
    "id": "00fee5ff-a55b-42fb-b7c7-d14f05ae0769",
    "status": "done",
    "result": 0.873,
    "result_details": {
        "is_valid": true,
        "message": "processed",
        "original_duration": 123.45,
        "is_truncated": true,
        "truncated_duration": 60.0,
        "mean_ai_prob": 0.873,
        "individual_chunks_ai_prob": [0.81, 0.90, 0.91]
    }
}

결과 상세

is_valid: 오디오 파일 유효 여부(true/false)
message: 처리 메시지
original_duration: 원본 오디오 길이(초)
is_truncated: 분석을 위해 오디오가 잘렸는지 여부
truncated_duration: 잘린 경우 분석된 길이
mean_ai_prob: 전체 AI 확률 점수
individual_chunks_ai_prob: 청크별 AI 확률 점수

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

사용자 크레딧 확인

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

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

요청 예시

curl -X 'GET' \
  'https://detect-audio.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-audio.truthscan.com/health

요청 예시

curl -X 'GET' \
  'https://detect-audio.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로 남은 크레딧 확인
필요 시 추가 크레딧 구매
analyzeUpToSeconds로 짧게 분석해 크레딧 소모 줄이기

입력 검증 문제

"Unsupported file format" (400)

원인: 지원하지 않거나 유효하지 않은 오디오 형식

해결:

지원 형식인지 확인(MP3, WAV, M4A, FLAC, OGG, MP4)
파일이 손상되지 않았는지 확인
업로드 시 Content-Type 헤더 확인

"File too large" (400)

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

해결:

100MB 미만으로 압축 또는 변환
업로드 전 파일 크기 확인
가능하면 MP3 등 효율적인 형식 사용

처리 문제

"Audio processing took too long"

원인: 오디오 처리 시간 초과 또는 타임아웃

해결:

더 작은 파일이나 더 짧은 길이로 시도
analyzeUpToSeconds로 앞부분만 분석
서버 부하가 높은지 확인
몇 분 후 요청 재시도

/query 응답에서 상태 "failed"

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

해결:

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

업로드 문제

"Audio upload failed" (403/400)

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

해결:

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

"Invalid pre-signed URL" (400)

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

해결:

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

도움이 필요하신가요?

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

문의하기

API 자주 묻는 질문

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