AI 휴머나이저 API: Humanizer API v2와 탐지 API

Academic Humanizer의 AI 휴머나이저 API는 개발자와 기관을 위한 두 가지 REST 엔드포인트를 제공합니다. 문장 단위 변경과 함께 휴머나이징된 텍스트를 반환하는 POST /api/v2/external/humanize, 그리고 최대 100,000자에 대한 AI 탐지 평가를 반환하는 POST /api/v2/external/detector입니다. 둘 다 서버 측 API 키를 사용하며 계정과 같은 크레딧 잔액에서 차감됩니다.

이 글에서는 API가 누구를 위한 것인지, 인증과 접근 제어가 어떻게 작동하는지, 각 엔드포인트가 무엇을 반환하는지, 크레딧이 어떻게 계산되는지 다룹니다. 전체 레퍼런스는 /docs에 있습니다.

AI Humanizer API는 누구를 위한 것인가

웹 에디터는 개인 연구자에게 맞습니다. API는 학술 텍스트를 대량으로 또는 자체 인터페이스 안에서 다루는 제품과 팀에 맞습니다.

• 자체 에디터 안에 휴머나이징 단계를 제공하려는 글쓰기 플랫폼.
• AI 탐지 신호를 자동 판정이 아니라 사람이 하는 검토 과정의 입력 중 하나로 필요로 하는 LMS와 교육 콘텐츠 도구.
• 편집자가 읽기 전에 고객 초안을 일관된 1차 처리에 거치게 하는 교정·편집 서비스.
• 연구비 문서나 보고서를 일괄 검사하려는 연구 지원 부서.

학생 과제와 관련된 용도라면 최종 결정은 사람이 내리도록 설계하세요. 탐지기 출력은 검토할 증거입니다. 그 이유는 학생의 저자성을 의심하기 전에 고려할 것에서 설명합니다.

인증, IP 허용 목록, 속도 제한

로그인한 상태에서 /api에서 키를 만드세요. 키는 생성 시 한 번만 표시되며 Academic Humanizer는 해시만 저장하므로, 곧바로 시크릿 매니저나 서버 환경 변수에 복사해 두세요. 브라우저나 모바일 코드에 절대 포함하지 마세요.

키는 X-API-Key 헤더로 보냅니다. 문서에서 권장하는 헤더이며, 서버는 Authorization 헤더의 bearer 토큰으로 보낸 키도 받습니다.

각 요청은 텍스트가 처리되기 전에 몇 가지 검사를 거칩니다.

1. 키 확인키가 존재하고 활성 상태여야 하며, 키에 연결된 계정도 활성 상태여야 합니다.
2. IP 허용 목록제한 모드에서는 등록한 IP나 CIDR 범위에서 온 요청만 허용됩니다.
3. 속도 제한키의 초당 한도를 넘는 요청은 HTTP 429로 거부됩니다.
4. 처리텍스트를 휴머나이징하거나 분석하고, 크레딧 잔액을 확인합니다.
5. 결과 저장결과가 계정에 저장되고 JSON으로 반환됩니다.

IP 접근에는 두 가지 모드가 있습니다. 유효한 키만 있으면 어떤 IP든 호출할 수 있는 공개 모드, 그리고 등록된 IP나 CIDR 블록만 호출할 수 있는 제한 모드입니다. 고정 송신 주소를 가진 프로덕션 서버라면 제한 모드를 켜 두는 것이 좋습니다. 기본 속도 제한은 초당 10건입니다.

Humanize 엔드포인트

요청 본문은 JSON이며 필수 필드 originalContent 하나와 선택 필드 researchField 하나로 구성됩니다. 연구 분야를 보낸다면 지원되는 이름 중 하나여야 합니다. Arts and Humanities, Social Sciences, Business and Economics, Engineering, Natural Sciences, Medical and Health Sciences입니다. 필요하지 않으면 생략하거나 null을 보내세요.

curl -X POST https://academichumanizer.ai/api/v2/external/humanize   -H "Content-Type: application/json"   -H "X-API-Key: YOUR_API_KEY"   -d '{"originalContent": "Paste the paragraph or abstract to humanize here.", "researchField": "Natural Sciences"}'

호출이 성공하면 HTTP 201과 함께 다음을 담은 JSON 본문이 반환됩니다.

• humanizedText: 재작성된 전체 텍스트.
• changedCount: 바뀐 문장 수.
• sentences: 문장 단위 항목의 배열로, 각 항목에는 원문 기준 시작·끝 오프셋, 원래 문장, 휴머나이징된 문장, changed 플래그가 들어 있습니다. 배열은 비어 있을 수 있습니다.

저장된 결과 ID는 X-Humanizer-Id 응답 헤더로 돌아오므로, 내 시스템의 요청을 사용자 계정에 저장된 결과와 연결할 수 있습니다. changed는 문장이 다시 쓰였는지를 알려 줄 뿐 AI 탐지 판정이 아니라는 점에 유의하세요. 탐지 판정이 필요하면 Detector 엔드포인트를 쓰세요.

문장 오프셋이 있으면 자체 인터페이스에서 diff를 간단히 보여 줄 수 있습니다. 바뀐 구간을 강조하고 사용자가 각각을 수락하거나 편집하게 하면 됩니다. AI 재작성은 오류를 만들거나 의미를 바꿀 수 있으므로, 사용자는 모든 결과물을 사용 전에 검토해야 합니다.

Detector 엔드포인트

Detector 엔드포인트는 최대 100,000자의 필수 필드 text 하나만 받습니다. 분석 상태, 글자 수, 소요 시간, 문서 전체 평가, 탐지기 결과, creditUsed를 반환합니다. 연구 분야는 여기서 쓰이지 않습니다.

일반적인 패턴은 먼저 Detector를 호출해 어떤 구간에서 신호가 나오는지 사용자에게 보여 주고, 사용자가 고른 섹션에만 Humanize를 호출하는 것입니다. 그러면 비용과 변경 범위를 모두 최소로 유지할 수 있습니다.

API 크레딧 계산 방식

두 엔드포인트 모두 키를 소유한 계정의 크레딧을 사용합니다. 계산 방식은 서로 다릅니다.

Humanize는 500자당 1크레딧이며 요청마다 올림으로 계산하고, 완성된 결과가 저장될 때만 청구됩니다. Detector는 5,000자당 1크레딧이며 올림으로 계산합니다. 잔액이 부족하면 부분 결과를 반환하지 않고 크레딧 부족 오류로 요청이 실패합니다. 요금제와 팩은 크레딧과 요금 안내에서 설명하며, 현재 가격은 /pricing에 있습니다.

처리해야 할 오류

오류 본문에는 기계가 읽을 수 있는 짧은 코드가 포함되므로, 메시지 텍스트가 아니라 코드로 분기 처리하세요.

자주 묻는 질문

API 키는 어떻게 받나요?

로그인한 뒤 /api를 여세요. 키를 만들고 즉시 복사한 다음(한 번만 표시됩니다) 서버에 보관하세요.

내 키를 사용할 수 있는 서버를 제한할 수 있나요?

네. IP 접근을 제한 모드로 바꾸고 API 호출을 허용할 IP나 CIDR 범위를 등록하세요. 그 밖의 곳에서 온 요청은 HTTP 403으로 거부됩니다.

API에 무료 사용량이 있나요?

API는 웹 앱과 같은 크레딧을 사용합니다. 새 계정은 무료 크레딧 10개를 한 번 받으며, 짧은 구절 몇 개로 Humanize 엔드포인트를 시험하기에 충분합니다.

결과물은 어떤 탐지기를 기준으로 확인하나요?

Academic Humanizer는 Turnitin, GPTZero, ZeroGPT, Copyleaks, Sapling, Originality.ai를 기준으로 검증됩니다. 다른 도구와 마찬가지로 결과는 탐지기마다 다르며, 어떤 결과도 보장되지 않습니다.

Academic Humanizer로 개발하기

이미 원고, 초록, 과제를 다루는 제품이라면, API로 사용자를 다른 곳으로 보내지 않고도 휴머나이징 단계나 탐지 검사를 추가할 수 있습니다. 테스트 키로 시작해 실제 문단 몇 개를 두 엔드포인트에 돌려 보고, 프로덕션에 들어가기 전에 /docs에서 전체 레퍼런스를 읽어 보세요.