Skip to main content
测试版

Nubint API 文档

Nubint API 的认证、端点和响应格式。稿件审阅、科研插图和证据综合,用同一个密钥调用。

概述

所有请求都是通过 HTTPS 发送的 JSON。稿件检查、论文检索和数据图表会在响应中直接返回结果。插图或文献综述等需要几分钟的工作会返回 taskId,结果通过任务查询读取。

基础地址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 可由 Starter、Pro、Max 方案的账户调用。免费方案账户的密钥调用会收到 403。密钥会保留,订阅后同一密钥可再次使用。

不要把密钥放进浏览器代码或公开仓库。只在服务器或本地环境变量中使用。

Nubint

参考文献真实性核验

POST/developer/review/reference-verification

将参考文献列表的每一条与学术索引比对,判断是否指向真实文献。不调用语言模型,相同输入得到相同结果。 如果参考文献在 `.bib` 文件中,也可以把内容放进 `referencesBibtex`(服务器会逐条转换并追加)。

请求

referencesstring[]

参考文献字符串数组。逐条放入 References 部分的条目,而不是正文。最多 100 条。有 DOI 请一并写入,匹配会更准确。

curl -X POST https://api.nubint.ai/api/v1/developer/review/reference-verification \
  -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 的条目数,即用户需要自行核对的数量。

Nubint

AI 写作检测

POST/developer/review/ai-detection

用独立的检测模型判断文本读起来是否像 AI 写的。按段落判定,并在被标记的段落中按排名指出起决定作用的句子。

safe 并不代表是人写的。为减少把人写的文字判为 AI 的误报,阈值设定较保守,漏检多于检出。被标记是信号,未被标记则是未知。不返回概率数值。

请求

textstring

要检查的文本。段落之间用空行分隔。最多 200,000 个字符。

cURL
curl -X POST https://api.nubint.ai/api/v1/developer/review/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": 40,
  "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。

Nubint

整篇稿件检查

POST/developer/review/manuscript-check

一次发送正文和参考文献,返回三个部分:参考文献真实性核验、AI 写作检测和来源质量。参考文献只匹配一次,两个相关部分看到的是同一批论文。 如果参考文献在 `.bib` 文件中,也可以把内容放进 `referencesBibtex`(服务器会逐条转换并追加)。

请求

textstring

稿件正文。为空时 AI 写作检测和来源质量为 skipped。最多 200,000 个字符。

referencesstring[]

参考文献字符串数组。为空时参考文献核验和来源质量为 skipped。最多 100 条。

cURL
curl -X POST https://api.nubint.ai/api/v1/developer/review/manuscript-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": 30
}
*.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。

Nubint

判定值

参考文献判定 (status)

verified

已在索引中确认:DOI 等标识符或标题一致。

uncertain

找到了候选,但标题只部分一致。请与 matchedTitle 对照。

off_index

无法用该索引确认。可能是专著、法规或非公开期刊等本来就不在索引中的文献。并不表示该文献不存在。

unparseable

无法作为书目条目读取的行(找不到标题、年份或作者)。

AI 写作检测判定 (verdict)

safe

本检查未发现 AI 写作特征。并不保证是人写的。

caution

部分段落有 AI 写作特征。请查看被标记的句子。

risk

多个段落有明显的 AI 写作特征。

inconclusive

可判定的正文不足(过短或以表格、列表为主)。并不表示不是 AI 写的。

Nubint

问题对象

AI 写作检测和来源质量的问题使用同一结构。

code

稳定的标识符。请根据该值选择界面文案。

anchor

出问题的原文句子。在作者-年份引用(如 APA)的稿件中,来源质量问题的 anchor 可能为空,此时用 reference 识别论文。

anchorStart

anchor 在你发送的 text 中的起始位置。同一句话出现两次时,字符串搜索会找到前一处 — 在文档中添加批注或高亮时请使用该值。无法确定位置时为 null。计数单位是 Unicode 码点,与 JavaScript 字符串索引(UTF-16)在表情符号等字符上不一致。

anchorEnd

anchor 的结束位置(anchorStart + 锚点长度)。

reference

问题所指论文的标识符(canonicalId)。

params

生成文案所用的值(参考文献编号、被引次数、排名等)。

message

用户语言的问题描述。仅在检查生成了文案时提供。

Nubint Figure

插图生成与修改

POST/developer/figure/start

根据描述绘制插图,或修改已有的插图。它会启动任务并立即返回 taskId,结果通过任务查询读取。插图也会放到项目画布上(响应中的 url)。

请求

promptstring

要画的内容、布局和标签。标签请用希望出现在图中的语言书写。generate 和 edit 时必填。

actionstring

要执行的操作 — generate(默认)、edit、recolor、remove_background、white_background、change_ratio、upscale、to_svg、to_pptx。除 generate 外,操作对象都是已有的插图。

kindstring

新绘制的插图的类型 — illustration(默认,插图和示意图)或 flowchart(由方框、箭头和文字构成的流程图、结构图)。

projectIdstring

放置结果的项目。留空会新建项目;传入相同的值,结果会放在同一张画布上。

baseImageUrlstring

要修改的插图的 imageUrl。留空时,以 projectId 中最近生成的插图为对象。

stylestring

风格 — flat、2.5d、3d、sketch、line-art、hand-drawn。

palettestring

配色。action 为 recolor 时必填。

ratiostring

比例 — 16:9、1:1、4:3 等。action 为 change_ratio 时必填。

upscaleTargetstring

action 为 upscale 时的目标尺寸 — 2k、4k、8k。

attachmentsstring[]

作为插图内容来源的文件的 fileUrl 数组。请先通过 /developer/figure/file 上传。

styleReferencesstring[]

作为外观参考的图片的 fileUrl 数组。不会沿用其内容。

cURL
curl -X POST https://api.nubint.ai/api/v1/developer/figure/start \
  -H "X-API-Key: $NUBINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Ligand-receptor signaling through the MAPK cascade (RAS, RAF, MEK, ERK) to target gene transcription",
    "style": "flat",
    "ratio": "16:9"
  }'

响应

{
  "taskId": "9f2c41d0...",
  "status": "running",
  "projectId": "5b0f7a3e...",
  "url": "https://app.nubint.ai/figure/5b0f7a3e..."
}
taskId

传给任务查询的值。24 小时内有效。

projectId

该插图所在的项目。在下一个请求中传入即可接着做。

url

在 Nubint Figure 中打开画布的地址。修改文字、重绘区域和导出都在这里进行。

result

任务查询的结果。插图返回 imageUrl,SVG、PPTX 返回 fileUrl,creditsCharged 为该任务使用的积分。

图中的文字由图像模型绘制,请提醒用户核对一遍拼写。用真实数据绘制的图表请使用 /developer/figure/plot,而不是此路径。

Nubint Figure

数据图表

POST/developer/figure/plot

用真实数据绘制图表。由代码而不是图像模型绘制,数值与表格完全一致,结果在同一个响应中返回。

请求

csvstring

CSV 文本。第一行是列名。数值请原样发送,不要四舍五入或补全。

dataFilestring

代替 csv — 以 purpose 为 data 上传到 /developer/figure/file 的表格(CSV、TSV、XLSX)的 fileUrl。Excel 文件读取第一个工作表。

journalStylestring

期刊风格 — general(默认)、nature、science、cell、plos-one、acs。按该期刊插图常用的宽度和字号绘制。不保证符合期刊的投稿要求。

chart.typestring

图表类型 — bar、line、scatter、box、violin、heatmap、histogram。

chart.x · chart.ystring

x 轴和 y 轴使用的列名。histogram 时,x 为要划分区间的数值列。

chart.groupBystring

用于划分系列的列。

chart.aggregatestring

bar、line 中合并 x 相同的行的方式 — mean(默认)、median、sum、count、none。

chart.errorstring

误差线 — none、sd、sem。

palette · ratiostring

配色和比例。

includeSvgboolean

为 true 时,还会返回可编辑的 SVG 文件(svgUrl)。会加收 SVG 导出的积分。

projectIdstring

放置图表的项目。

cURL
curl -X POST https://api.nubint.ai/api/v1/developer/figure/plot \
  -H "X-API-Key: $NUBINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "csv": "group,glucose\ncontrol,5.1\ncontrol,5.4\nrestricted,6.2\nrestricted,6.0",
    "chart": { "type": "bar", "x": "group", "y": "glucose", "error": "sd", "showPoints": true }
  }'

响应

200 OK
{
  "imageUrl": "https://.../plot.png",
  "summary": {
    "type": "bar", "rowsRead": 4, "rowsPlotted": 4,
    "rowsDropped": 0, "errorBars": "sd"
  },
  "url": "https://app.nubint.ai/figure/5b0f7a3e..."
}
imageUrl

图表 PNG(300 dpi)。

summary

实际绘制的值 — 读取、绘制和剔除的行数,以及各系列的 n、均值和标准差。提到数字时请引用这些值。

creditsCharged

该请求扣除的积分。无法绘制的表格(缺少列或没有数值)不扣积分,并返回 400。

Nubint Evidence

论文检索

POST/developer/search/papers

用研究问题或关键词检索学术索引(OpenAlex、KCI)。不消耗积分,结果立即返回。

请求

querystring

研究问题或关键词。任何语言均可。

limitinteger

返回的论文数量。默认 10,最多 30。

yearFrom · yearTointeger

出版年份范围。只给一端也可以。

minCitations · openAccessOnly · excludeRetracted

最低被引次数、仅限开放获取、排除已撤稿论文。只应用传入的条件。

sortstring

排序 — relevance(默认)、cited、recent、oldest。

cURL
curl -X POST https://api.nubint.ai/api/v1/developer/search/papers \
  -H "X-API-Key: $NUBINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "sleep restriction and insulin sensitivity", "limit": 3 }'

响应

200 OK
{
  "papers": [
    {
      "id": "https://doi.org/10.1016/s0140-6736(99)01376-8",
      "title": "Impact of sleep debt on metabolic and ...",
      "year": 1999,
      "venue": "The Lancet"
    },
    ...
  ]
}
papers[].id

论文标识符。保存到文献库时直接使用。

papers[].supportingPassage

原文已被索引时,会一并返回与查询相符的段落。

note

没有结果时附带的说明。查询中没有可检索的主题时,也会返回空结果。

Nubint Evidence

文献综述

POST/developer/evidence/literature-review

根据研究问题撰写文献综述。检索索引、选出核心论文,并以 Markdown 返回综述,引用编号与参考文献一一对应。以任务方式运行,需要几分钟。

请求

questionstring

研究问题或主题。

depthstring

深度 — fast(默认)、balanced、comprehensive。越深,引用的论文数、耗时和积分越多。

languagestring

结果使用的语言 — ko、en、ja、zh。留空则为英语。

cURL
curl -X POST https://api.nubint.ai/api/v1/developer/evidence/literature-review \
  -H "X-API-Key: $NUBINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Does sleep restriction impair glucose metabolism in healthy adults?",
    "depth": "fast",
    "language": "en"
  }'

响应

{
  "taskId": "9f2c41d0...",
  "threadId": "0199c2e4...",
  "status": "running"
}
threadId

这次文献综述的句柄。在任务查询中用它代替 taskId,即使超过 24 小时也能再次读取结果。

url

在 Nubint 中打开结果的地址。

result

任务查询的结果 — 综述正文和 references(与正文中 [n] 的顺序一致)。

Nubint Evidence

系统评价 · 数据提取

即将推出

系统评价(方案提议、筛选、综合报告)和数据提取即将推出。目前无法通过 API 或 MCP 使用,调用相应路径会返回 403。

目前可以使用的是论文检索和文献综述。推出后,会在本文档中补充请求与响应格式。

通用

任务查询

POST/developer/tasks/get

启动任务的路径会立即返回 taskId。把 taskId 发送到此路径即可读取结果。请每隔 15 到 30 秒查询一次,不要因为慢就重新启动同一任务 — 每次启动都会重新计费。

请求

taskIdstring

启动响应中的 taskId。24 小时内有效。

threadIdstring

用它代替 taskId,可随时再次读取以往工作的最新结果。

cURL
curl -X POST https://api.nubint.ai/api/v1/developer/tasks/get \
  -H "X-API-Key: $NUBINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "9f2c41d0..." }'

响应

200 OK
{
  "status": "completed",
  "result": {
    "imageUrl": "https://.../figure.png",
    "mimeType": "image/png"
  },
  "projectId": "5b0f7a3e...",
  "url": "https://app.nubint.ai/figure/5b0f7a3e..."
}
status

running、completed、failed、cancelled。

result

completed 时的结果。结构因任务而异(见上文各节)。

error

failed 时的原因。

url

在 Nubint 中打开结果的地址。

启动任务的请求,以及图表和稿件保存请求,都可以带上 idempotencyKey。每个请求使用你自己设定的值,因没收到响应而重发时使用相同的值 — 不会重新启动,而是原样返回第一次的响应(replayed: true),积分也只扣一次。该值保留 24 小时。

价格

AI 写作检测每 1 万 token 88 积分,来源质量每 1 万 token 66 积分。正文篇幅按英文 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

需要 Starter、Pro 或 Max 方案。

422

请求体格式不符(字段名或类型)。

429

超出请求限额。请 1 分钟后重试。

502

AI 写作检测服务无响应(/developer/review/ai-detection)。请稍后重试。

503

暂时无法完成认证校验。不是密钥的问题,请勿吊销,稍后重试即可。

限额与响应时间

每个请求最多 100 条参考文献、200,000 个字符的正文(约 80 页英文 A4)。

响应是同步的,参考文献较多时可能需要数十秒。请把客户端超时设为 120 秒以上。

每个账户的请求限额:参考文献核验每分钟 30 次,AI 写作检测和整篇稿件检查每分钟 10 次。超出会收到 429。

全部端点

所有 MCP 工具都可以通过 REST 调用。路径为 /developer/ 后接分组和功能名称(例如 /developer/evidence/literature-review),以 JSON 形式 POST 与 MCP 工具相同的参数,即可得到相同的结果。套餐、请求限额和积分也相同。

标为“任务”的路径会启动需要几分钟的工作,并立即返回 taskId。将 taskId 发送到 /developer/tasks/get 即可读取结果。请每隔 15 到 30 秒查询一次。

POST /developer/search/papers即时

search_papers

POST /developer/search/library即时

search_library

POST /developer/search/save-to-library即时

save_to_library

POST /developer/review/manuscript-check即时

run_manuscript_check

POST /developer/review/reference-verification即时

run_manuscript_check

POST /developer/review/ai-detection即时

run_manuscript_check

POST /developer/review/manuscript即时

save_manuscript

POST /developer/review/start任务

start_review

POST /developer/evidence/literature-review任务

start_literature_review

POST /developer/evidence/systematic-review即将推出

start_systematic_review

POST /developer/evidence/screened-papers即将推出

list_screened_papers

POST /developer/evidence/screening即将推出

update_screening

POST /developer/evidence/systematic-review-report即将推出

start_systematic_review_report

POST /developer/evidence/extract-data即将推出

start_extract_data

POST /developer/evidence/export即将推出

export_evidence

POST /developer/figure/project即时

open_figure_project

POST /developer/figure/file即时

upload_figure_file

POST /developer/figure/start任务

start_figure

POST /developer/figure/plot即时

create_figure_plot

POST /developer/tasks/get即时

get_task

POST /developer/tasks/list即时

list_tasks

POST /developer/credits/get即时

get_credits

MCP

除稿件检查(run_manuscript_check — 参考文献真实性核验和 AI 写作检测可通过 checks 单独运行)外,MCP 服务器还提供论文检索、七种稿件审阅、文献综述和插图工具。系统评价和数据提取即将推出。ChatGPT、Claude 通过登录(OAuth)连接,无需 API 密钥 — 请查看 MCP 连接说明。

MCP 连接方法

工具列表

服务器当前提供的工具。以 start_ 开头的工具会启动需要几分钟的任务并立即返回,结果通过 get_task 读取。

search_papers即时

AI论文检索

search_library即时

AI论文检索

save_to_library即时

AI论文检索

run_manuscript_check即时

AI论文审阅

save_manuscript即时

AI论文审阅

start_review任务

AI论文审阅

start_literature_review任务

Nubint Evidence

open_figure_project即时

Nubint Figure

upload_figure_file即时

Nubint Figure

start_figure任务

Nubint Figure

create_figure_plot即时

Nubint Figure

get_task即时

通用

list_tasks即时

通用

get_credits即时

通用

在开发工具中用 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_..."