Skip to main content
베타

API 문서

투고 전 점검 API의 인증, 엔드포인트, 응답 형식을 정리했습니다.

개요

모든 요청은 HTTPS로 보내는 JSON이고, 결과는 응답에 바로 담겨 돌아옵니다. 작업 ID를 받아 다시 조회하는 비동기 방식이 아닙니다.

기본 주소https://api.nubint.ai/api/v1

응답 필드 이름은 camelCase입니다. 예외로 서지(csl)는 CSL-JSON 표준 키(container-title, DOI 등)를, 지적의 params는 snake_case 키를 그대로 씁니다.

인증

요청마다 X-API-Key 헤더에 API 키를 넣습니다. Authorization 헤더가 아닙니다.

Header
X-API-Key: nbk_live_...

키는 누빈트 앱의 설정 → API/MCP에서 발급합니다. nbk_live_로 시작하고 발급 직후 한 번만 보여 줍니다. 서버에는 해시만 저장하므로 잃어버리면 새로 발급해야 합니다.

계정당 활성 키는 10개까지입니다. 유출이 의심되면 같은 화면에서 바로 폐기하세요. 폐기한 키는 즉시 거절됩니다.

API는 Pro·Max 요금제 계정에서 호출할 수 있습니다. 무료 요금제 계정의 키로 부르면 403을 받습니다 — 키는 그대로 남고, 구독하면 같은 키가 다시 동작합니다.

키를 브라우저 코드나 공개 저장소에 넣지 마세요. 서버나 로컬 환경 변수에서만 쓰세요.

참고문헌 실존 확인

POST/citations/verify

참고문헌 목록의 각 항목이 실제 문헌을 가리키는지 학술 색인과 대조합니다. 언어 모델을 부르지 않아 같은 입력에는 같은 결과가 나옵니다.

요청

referencesstring[]

참고문헌 문자열 배열. 본문이 아니라 References 섹션의 항목을 한 줄씩 넣습니다. 최대 100건. DOI가 있으면 함께 두세요 — 매칭이 정확해집니다.

curl -X POST https://api.nubint.ai/api/v1/citations/verify \
  -H "X-API-Key: $NUBINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "references": [
      "Spiegel, K., Leproult, R., & Van Cauter, E. (1999). Impact of sleep debt on metabolic and endocrine function. The Lancet, 354(9188), 1435-1439.",
      "Anderson, R. T., & Liu, M. (2023). Chronotype misalignment and cognitive load in higher education. Educational Neuroscience Quarterly, 11(4), 501-519."
    ]
  }'

응답

200 OK
{
  "results": [
    {
      "text": "Spiegel, K., Leproult, R., & Van Cauter, E. (1999). ...",
      "status": "verified",
      "basis": "title_exact",
      "paper": {
        "canonicalId": "https://doi.org/10.1016/s0140-6736(99)01376-8",
        "csl": {
          "type": "article-journal",
          "title": "Impact of sleep debt on metabolic and endocrine function",
          "container-title": "The Lancet",
          "DOI": "10.1016/s0140-6736(99)01376-8"
        }
      },
      "csl": null,
      "matchedTitle": "Impact of sleep debt on metabolic and endocrine function",
      "nearMissTitle": null
    },
    {
      "text": "Anderson, R. T., & Liu, M. (2023). ...",
      "status": "off_index",
      "basis": "parsed",
      "paper": null,
      "csl": {
        "type": "article-journal",
        "title": "Chronotype misalignment and cognitive load in higher education",
        "container-title": "Educational Neuroscience Quarterly"
      },
      "matchedTitle": null,
      "nearMissTitle": null
    }
  ],
  "summary": {
    "total": 2,
    "verified": 1,
    "uncertain": 0,
    "offIndex": 1,
    "unparseable": 0,
    "needsReview": 1
  }
}
status

판정. 아래 '판정 값'을 참고하세요.

basis

판정 근거 — identifier(DOI 등 식별자 일치), title_exact, title_strong, title_partial, parsed(색인 밖, 서지만 읽음), none.

paper

색인에서 찾은 논문의 서지와 식별자. verified와 uncertain일 때만 채워집니다.

csl

색인 밖 문헌을 원문에서 읽어 낸 서지(CSL-JSON). off_index일 때만 채워집니다.

matchedTitle

채택된 색인 후보의 제목. uncertain일 때 사용자가 자기 참고문헌과 대조하는 데 씁니다.

nearMissTitle

제목이 충분히 겹치지 않아 버린 후보의 제목(off_index일 때만). 원고 쪽 표기가 틀린 경우 고칠 단서입니다. 채택된 매칭이 아니므로 인용으로 쓰면 안 됩니다.

summary

집계. needsReview는 verified가 아닌 전부, 즉 사용자가 직접 확인할 건수입니다.

AI 작성 감지

POST/preflight/ai-detection

텍스트가 AI로 작성된 것처럼 읽히는지 독립된 감지 모델로 판정합니다. 문단 단위로 판정하고, 걸린 문단에서는 판정을 이끈 문장을 순위와 함께 짚습니다.

safe는 사람이 썼다는 뜻이 아닙니다. 사람 글을 AI로 판정하는 오탐을 줄이도록 기준을 보수적으로 잡아, 놓치는 경우가 잡는 경우보다 많습니다. 걸리면 신호이고, 안 걸리면 모르는 것입니다. 확률 숫자는 반환하지 않습니다.

요청

textstring

검사할 텍스트. 문단은 빈 줄로 구분합니다. 최대 200,000자.

cURL
curl -X POST https://api.nubint.ai/api/v1/preflight/ai-detection \
  -H "X-API-Key: $NUBINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Full manuscript text, paragraphs separated by blank lines..." }'

응답

200 OK
{
  "verdict": "caution",
  "checked": 9,
  "flagged": 2,
  "creditsCharged": 20,
  "issues": [
    {
      "code": "possibly",
      "category": "possibly",
      "anchor": "The sentence in your manuscript that drove the flag.",
      "reference": null,
      "params": {
        "lang": "en",
        "rank": 1,
        "rank_total": 2,
        "unit_tokens": 142,
        "reasons": [
          { "code": "sentence_contribution", "rank": 1, "total": 2 }
        ]
      },
      "message": null
    }
  ]
}
verdict

문서 전체 판정 — safe · caution · risk · inconclusive.

checked

판정한 문단 수.

flagged

단계가 붙은 문단 수.

creditsCharged

이 요청에 청구된 크레딧. inconclusive 는 0.

issues

걸린 문장 목록. code는 단계(likely · possibly), anchor는 원문 문장, params.rank는 그 문단 안에서의 순위입니다.

감지 서비스가 응답하지 않으면 이 엔드포인트는 502를 돌려줍니다. 결과 없이 safe를 내보내지 않습니다.

원고 전체 점검

POST/preflight/check

본문과 참고문헌을 한 번에 보내면 참고문헌 실존 확인, AI 작성 감지, 출처 품질 세 섹션을 돌려줍니다. 참고문헌 매칭은 한 번만 수행해 두 섹션이 같은 논문을 봅니다.

요청

textstring

원고 본문. 비우면 AI 작성 감지와 출처 품질이 skipped 됩니다. 최대 200,000자.

referencesstring[]

참고문헌 문자열 배열. 비우면 참고문헌 확인과 출처 품질이 skipped 됩니다. 최대 100건.

cURL
curl -X POST https://api.nubint.ai/api/v1/preflight/check \
  -H "X-API-Key: $NUBINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Full manuscript text...",
    "references": [
      "Spiegel, K., Leproult, R., & Van Cauter, E. (1999). Impact of sleep debt on metabolic and endocrine function. The Lancet, 354(9188), 1435-1439.",
      "Anderson, R. T., & Liu, M. (2023). Chronotype misalignment and cognitive load in higher education. Educational Neuroscience Quarterly, 11(4), 501-519."
    ]
  }'

응답

AI 작성 감지가 실패한 예입니다. 나머지 섹션은 그대로 결과를 냅니다 (일부 필드 생략).

200 OK
{
  "citations": {
    "status": "ok",
    "reason": null,
    "summary": { "total": 2, "verified": 1, "offIndex": 1, "needsReview": 1, ... },
    "results": [ ... ]
  },
  "aiDetection": {
    "status": "failed",
    "reason": "TimeoutError: detection service did not respond",
    "verdict": null,
    "checked": 0,
    "flagged": 0,
    "issues": []
  },
  "sourceQuality": {
    "status": "ok",
    "reason": null,
    "checked": 1,
    "issues": []
  },
  "creditsCharged": 15
}
*.status

섹션마다 따로 있습니다 — ok(검사함), failed(우리 쪽 장애로 못 함, 다시 시도하면 됨), skipped(입력이 없어 건너뜀). failed와 skipped에는 reason이 붙습니다.

sourceQuality

확인된 참고문헌만 검사합니다 — 철회(retracted_source), 우려 표명(expression_of_concern), 프리프린트(preprint_source · preprint_has_published_version), 인용이 적은 출처(low_citation_source) 등.

creditsCharged

이 요청에 청구된 크레딧. 성공한 섹션만 과금하고 failed·skipped 와 AI 감지 inconclusive 는 0.

판정 값

참고문헌 판정 (status)

verified

색인에서 확인됨. DOI 등 식별자나 제목이 일치합니다.

uncertain

후보는 찾았지만 제목이 부분적으로만 일치합니다. matchedTitle과 대조해 보세요.

off_index

이 색인으로는 확인하지 못했습니다. 단행본 · 법령 · 비공개 학술지처럼 원래 색인에 없는 문헌일 수 있습니다. 존재하지 않는다는 뜻이 아닙니다.

unparseable

서지 항목으로 읽을 수 없는 줄입니다 (제목 · 연도 · 저자를 찾지 못함).

AI 작성 감지 판정 (verdict)

safe

이 검사로는 AI 작성 특징을 찾지 못했습니다. 사람이 썼다는 보증이 아닙니다.

caution

일부 문단에 AI 작성 특징이 있습니다. 해당 문장을 확인하세요.

risk

여러 문단에 뚜렷한 AI 작성 특징이 있습니다.

inconclusive

판정할 산문이 부족합니다 (너무 짧거나 표 · 목록 위주). AI가 아니라는 뜻이 아닙니다.

지적 객체

AI 작성 감지와 출처 품질의 지적은 같은 형태입니다.

code

안정적인 식별자. 화면 문구를 이 값으로 고르세요.

anchor

문제가 된 원문 문장. 저자-연도 인용(APA 등) 원고에서는 출처 품질 지적의 anchor가 비어 있을 수 있습니다. 그때는 reference로 논문을 식별합니다.

reference

지적 대상 논문의 식별자(canonicalId).

params

문구를 만드는 데 쓰는 값(참고문헌 번호, 인용 수, 순위 등).

message

사용자 언어로 된 지적 문구. 검사가 문구를 만든 경우에만 채워집니다.

요금

AI 작성 감지는 1만 토큰당 44크레딧, 출처 품질은 1만 토큰당 32크레딧입니다. 본문 분량은 영문 A4 5장 단위로 올림하며, 그 한 단위가 최소 과금입니다. 에디터의 AI 검토와 같은 단가입니다.

참고문헌 확인은 무료입니다. 우리 쪽 장애로 실패한 섹션(failed), 입력이 없어 건너뛴 섹션(skipped), 판정할 산문이 부족한 AI 감지(inconclusive)는 차감하지 않습니다.

실행 전에 예상 비용을 확인해, 잔액이 모자라면 실행하지 않고 402를 돌려줍니다.

오류

오류 응답 본문은 detail 필드 하나를 가진 JSON입니다.

401 Unauthorized
{ "detail": "Invalid API key" }
400

한도 초과 — 참고문헌 100건 또는 본문 200,000자를 넘었습니다. 잘라서 처리하지 않습니다.

401

X-API-Key 헤더가 없거나, 키가 잘못되었거나, 폐기된 키입니다.

402

크레딧이 부족합니다 — 잔액이 0이거나 이 요청의 예상 비용을 감당하지 못합니다. 검사는 실행되지 않았습니다.

403

Pro·Max 요금제가 필요합니다.

422

요청 본문 형식이 맞지 않습니다(필드 이름 · 타입).

429

요청 한도를 넘었습니다. 1분 뒤 다시 시도하세요.

502

AI 작성 감지 서비스가 응답하지 않았습니다(/preflight/ai-detection). 잠시 후 다시 시도하세요.

503

인증 확인이 일시적으로 불가능합니다. 키 문제가 아니니 폐기하지 말고 다시 시도하세요.

한도와 응답 시간

참고문헌은 요청당 100건, 본문은 200,000자(영문 A4 약 80쪽)까지입니다.

응답이 동기식이라 참고문헌이 많으면 수십 초가 걸릴 수 있습니다. 클라이언트 타임아웃을 120초 이상으로 두세요.

요청 한도는 계정당 참고문헌 확인 분당 30회, AI 작성 감지와 원고 전체 점검 분당 10회입니다. 넘으면 429를 받습니다.

MCP

같은 세 검사를 MCP 도구(preflight_check · verify_citations · detect_ai_writing)로도 제공합니다. ChatGPT·Claude는 로그인(OAuth)으로 연결하고 API 키가 필요 없습니다 — MCP 연결 안내를 보세요.

MCP 연결 방법

개발 도구에서 API 키로 연결

헤더를 설정할 수 있는 개발 도구는 X-API-Key 로 연결할 수 있습니다. 서버 주소는 같습니다.

터미널에서 한 줄로 추가합니다. 추가한 뒤 /mcp 로 연결 상태를 확인할 수 있습니다.

Claude Code
claude mcp add --transport http nubint https://api.nubint.ai/api/v1/mcp \
  --header "X-API-Key: nbk_live_..."