测试版

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_...

在 Nubint 应用的设置 → 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 万 token 44 积分，来源质量每 1 万 token 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 个字符的正文(约 80 页英文 A4)。

响应是同步的，参考文献较多时可能需要数十秒。请把客户端超时设为 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_..."