AI 텍스트 탐지 API
애플리케이션에 TruthScan AI 탐지 API를 통합하기 위한 전체 문서입니다.
코드 없이 FastAPI 엔드포인트에서 직접 테스트해 보세요: https://detect-text.truthscan.com/docs
인증
TruthScan은 API 접근을 위해 API 키를 사용합니다. API 키는 개발자 포털 계정 페이지 상단에 있습니다.
TruthScan은 모든 API 요청에 아래와 같은 형태의 요청 본문에 API 키를 포함할 것을 요구합니다:
{
"key": "YOUR API KEY GOES HERE"
}YOUR API KEY GOES HERE를 본인의 API 키로 반드시 바꿔야 합니다.
웹소켓 시나리오에서는 URL에 조직 ID(Organization ID)를 포함해야 합니다. 조직 ID는 개발자 포털 계정 페이지 상단에서 확인할 수 있습니다.
TruthScan은 모든 웹소켓 요청 URL에 조직 ID가 포함되기를 요구합니다. 문서 예시는 다음과 같습니다:
wss://detect-text.truthscan.com/ws/$ORG_ID$ORG_ID를 본인의 조직 ID로 반드시 바꿔야 합니다.
AI 탐지기
탐지
이 엔드포인트로 텍스트를 AI 탐지에 제출할 수 있습니다. 최상의 정확도를 위해 최소 약 200단어를 권장합니다.
POST https://detect-text.truthscan.com/detect임계값
이 엔드포인트는 1~100 범위의 "result" 점수를 반환합니다. 최적 정확도 기준으로 50 미만은 확실히 인간 작성, 50~60은 AI 가능성, 60 초과는 AI로 판단합니다. 메인 "result" 점수는 99%+ 정확도입니다.
Writer, Copyleaks 등 다른 탐지기 점수는 근사치이며 메인 "result" 점수만큼 정확하지 않습니다.
줄바꿈
JSON으로 보낼 때 문자열 안에서 줄바꿈은 \n으로 인코딩해야 합니다.
요청 예시
curl -X 'POST' \
'https://detect-text.truthscan.com/detect' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"text": "On Citizen science\nCitizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
"key": "YOUR-API-KEY-GOES-HERE",
"model": "xlm_ud_detector",
"retry_count": 0
}'요청 입력은 30,000단어 미만이어야 합니다.
응답 예시
{
"id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
"input": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
"model": "xlm_ud_detector",
"result": null,
"result_details": null,
"status": "pending",
"retry_count": 0
}응답에는 서버가 부여한 문서 ID가 포함됩니다. 이 시점에서 문서는 처리 대기열에 들어갑니다. /query로 AI 탐지 요청 상태를 조회할 수 있습니다. 평균 완료 시간은 약 2~4초이며, 단어 수에 따라 더 걸릴 수 있습니다.
조회
/detect가 반환한 문서 ID를 받습니다. 문서 제출 상태와 서드파티 AI 탐지기가 처리한 AI 탐지 결과를 반환합니다.
POST https://detect-text.truthscan.com/query요청 예시
curl -X 'POST' \
'https://detect-text.truthscan.com/query' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"id": "DOCUMENT-ID-GOES-HERE"
}'응답 예시
{
"id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
"model": "xlm_ud_detector",
"result": 12.0,
"result_details": {
"scoreGptZero": 50.0,
"scoreOpenAI": 0.0,
"scoreWriter": 0.0,
"scoreCrossPlag": 0.0,
"scoreCopyLeaks": 50.0,
"scoreSapling": 0.0,
"scoreContentAtScale": 0.0,
"scoreZeroGPT": 50.0,
"human": 88.0
},
"status": "done",
"retry_count": 0
}여기서 "result": 12.0은 입력의 "인간적 정도"를 나타냅니다. 50% 임계값 미만이므로 텍스트는 확실히 인간 작성입니다. result_details 하위 값도 입력의 인간적 정도를 나타냅니다. 예: "scoreZeroGPT": 50.0은 ZeroGPT 기준 약 50% 인간 작성으로 본다는 뜻이며, 다른 탐지기도 동일한 방식으로 해석합니다.
사용자 크레딧 확인
이 엔드포인트는 헤더로 사용자 apikey를 받아 크레딧 정보를 반환합니다.
GET https://detect-text.truthscan.com/check-user-credits요청 예시
curl -X 'GET' \
'https://detect-text.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 탐지
문장 단위 AI 탐지기는 웹소켓 기반 프로토콜 위에서 동작합니다.
텍스트에 대한 문장 단위 결과를 얻기 위해 필요한 단계:
- 웹소켓에 연결
- 웹소켓에서 수신하는 모든 이벤트 수신
- document_watch 요청 전송
- document_id 이벤트 수신
- document_id 응답으로 생성된 id로 문서를 AI 탐지에 제출
- document_chunk 이벤트 수신 시작. document_chunk는 각 문장과 문장 단위 결과를 반환
- 문서 처리가 끝나면 document_done 이벤트 수신
웹소켓 연결
이 엔드포인트로 웹소켓 연결을 수립합니다
wss://detect-text.truthscan.com/ws/$ORG_ID예제 코드
ws = new WebSocket("wss://detect-text.truthscan.com/ws/1722238709737x2194626580942121212");웹소켓에서 수신하는 모든 이벤트 수신
웹소켓 연결이 수립되면 연결을 통해 전송되는 이벤트를 수신합니다.
예제 코드
ws.addEventListener("message", (event) => {
console.log("Message from server ", event.data);
});document_watch 요청 전송
문서 전송 의사를 웹소켓으로 document_watch 요청을 보내 표시합니다
예제 코드
ws.send(JSON.stringify({
"event_type": "document_watch",
"api_key": "$API_KEY",
}))document_id 이벤트 수신
document_watch 이벤트를 보낸 후 서버가 document_id 이벤트를 반환합니다.
응답 예시
{
"event_type": "document_id",
"success": true,
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}AI 탐지 요청 제출
document_id 응답으로 생성된 id를 사용해 문서를 AI 탐지에 제출합니다
POST https://detect-text.truthscan.com/detect요청 예시
curl -X 'POST' \
'https://detect-text.truthscan.com/detect' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"text": "Citizen science involves the public participating in scientific research. This can take many forms, collecting data on local wildlife populations to analyzing astronomical images. Citizen science projects allow researchers to gather large amounts of data and engage the public in the process. By participating, individuals contribute to valuable research while gaining a deeper understanding of the scientific world around them.",
"key": "YOUR-API-KEY-GOES-HERE",
"model": "xlm_ud_detector",
"id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}'문장 단위 결과 수신
document_chunk 이벤트 수신을 시작합니다. document_chunk는 각 문장과 문장 단위 결과를 반환합니다
응답 예시
{
"event_type": "document_chunk",
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
"model": "xlm_ud_detector",
"chunk": "Citizen science involves the public in scientific research.",
"result": 0.714
}문서 처리가 끝나면 document_done 이벤트를 받습니다.
응답 예시
{
"event_type": "document_done",
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
"model": "xlm_ud_detector"
}예외 상황 처리
AI 탐지 수행 중 서버 오류가 발생하면 document_error 이벤트가 웹소켓 클라이언트로 전송됩니다. 클라이언트는 적절히 대응해야 합니다(예: UI에 오류 메시지 표시).
예: 청크 이벤트 전체에 20초를 초과하면 서버가 REQUEST_TIMEOUT 오류 코드를 보냅니다.
{
"event_type": "document_error",
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa",
"error_code": "REQUEST_TIMEOUT",
"message": "Request timeout. Took 20 seconds."
}취소
UI에서 작업을 취소해야 하는 경우가 있습니다. 사용자가 창을 닫거나 명시적으로 취소하는 경우
이 경우 document_halt 이벤트를 보내야 합니다
응답 예시
{
"event_type": "document_halt",
"document_id": "512da191-166926922-44cb-81c6-191ae3a807aa"
}오류
대부분의 오류는 API에 잘못된 파라미터를 보낼 때 발생합니다. 각 호출의 파라미터 형식을 다시 확인하고 예제 코드를 실행해 보세요.
사용하는 일반 오류 코드는 REST 표준을 따릅니다:
| 오류 코드 | 의미 |
|---|---|
| 400 | Bad Request -- 요청이 유효하지 않습니다. |
| 403 | Forbidden -- API 키가 유효하지 않거나 크레딧이 부족합니다(단어당 0.1). |
| 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로 남은 크레딧 확인
- 필요 시 추가 크레딧 구매
- 짧은 텍스트로 크레딧 소모 줄이기
입력 검증 문제
"Input text cannot be empty" (400)
원인: 빈 텍스트 또는 공백만 제출됨
해결:
- 텍스트 입력이 비어 있지 않은지 확인
- 앞뒤 공백 제거
- 텍스트 인코딩이 올바른지 확인
"Input email is empty" (400)
원인: URL 처리에 이메일 누락
해결:
- URL 제출 시 유효한 이메일 제공
- 이메일 형식 확인
처리 문제
"Request timeout" (WebSocket)
원인: 문서 처리 시간 초과(120초 초과)
해결:
- 더 짧은 텍스트로 시도
- 서버 부하가 높은지 확인
- 요청 재시도
문서 상태 "failed"
원인: 다양한 이유로 처리 실패
해결:
- 입력 텍스트가 최소 요건을 충족하는지 확인
- 지원 형식인지 확인
- 다른 모델로 시도
- 문제가 지속되면 지원팀에 문의
웹소켓 연결 문제
연결 끊김
원인: 네트워크 문제 또는 서버 연결 종료
해결:
- 네트워크 연결 확인
- 재연결 로직 구현
- 웹소켓 URL이 올바른지 확인
"User not found" (WebSocket)
원인: 웹소켓 연결에 잘못된 조직 ID
해결:
- 조직 ID가 정확한지 확인
- 사용자 계정이 활성인지 확인
- 필요 시 재인증
API 자주 묻는 질문
AI 탐지 API에 대한 가장 흔한 질문과 답변입니다.