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