API 文件

一個端點。格式版本 4。Base URL https://api.consensis.app。

驗證身分

每個請求都帶 API 金鑰 —— Authorization: Bearer pk_live_… 或 X-API-Key 標頭。登入(Google 或 email,登入即建立帳戶)後在帳戶頁簽發金鑰。明文金鑰只顯示一次;我們只保存摘要。比對不到的金鑰回 401 —— 打錯的金鑰絕不會靜默降級成匿名試用,所以你永遠知道一件工作是記在哪個帳戶上。

免費試用 —— 不必金鑰、不必帳戶

免費試用直接從 API 就能用:每個位址每天 10 頁免費,完全不帶 Authorization 標頭(網頁上傳器另有獨立的 10 頁;超過額度時回應會帶 Retry-After)。

# 完全匿名 —— 不必金鑰、不必註冊
curl -X POST https://api.consensis.app/v1/parse -F "[email protected]"
# → 202 {"id": "…", "status": "queued", ...} — 輪詢方式同下

三行開始

curl -X POST https://api.consensis.app/v1/parse \
     -H "Authorization: Bearer pk_live_…" \
     -F "[email protected]" -F "pages=10"
# → 202 {"id": "b7f395cf7fbc", "status": "queued", ...}

curl -H "Authorization: Bearer pk_live_…" \
     https://api.consensis.app/v1/parse/b7f395cf7fbc
# → 輪詢到 "status": "done" 為止,之後 usage 與 result 就會一併附上

curl -OJ -H "Authorization: Bearer pk_live_…" \
     "https://api.consensis.app/v1/parse/b7f395cf7fbc/export?format=xlsx"

非同步 —— POST 立刻回 202;之後用 id 追蹤。10 頁冷啟動約需 600 秒;命中快取快得多。不要用 stage 推斷是否完成 —— 那個字串是給人看的;請看 status。

每一格帶什麼

這就是這個 API 賣的東西。不是「擷取更準」—— 而是每一格都能交代自己的來歷。

{"value": "1432",
 "confidence": "verified",
 "sources": ["vision-1", "vision-2"],
 "bbox": [436.5, 577.7, 459.8, 591.9]}

兩個獨立讀取結果一致,所以這一格是 verified,不帶 readings —— 值就是值。

readings 是關鍵差異:讀取結果不一致時你會拿到每個版本 —— 我們不會靜默挑一個。挑錯了,你根本不知道該看哪裡。只在有不一致時出現:

{"value": "1432",
 "confidence": "disputed",
 "provisional": true,
 "sources": ["vision-1", "vision-2"],
 "readings": {"vision-1": "1432", "vision-2": "1482"}}

provisional

只在 confidence 為 disputed 時出現,而且永遠是 true。

confidence

sources

這些不是廠商名稱。稽核問的是「有幾個獨立讀取結果」,不是「哪一家廠商」。

bbox

[x0, y0, x1, y1],單位是 PDF 點(1/72 英吋),原點在左上;頁碼在表格的 page 上。

一張表長什麼樣

上一節說的是一格帶什麼。這一節說一張表是怎麼圍著這些格子成形的。

{
 "page": 7,
 "index": 0,
 "order": null,
 "kind": null,
 "layout_disputed": true,
 "column_major": false,
 "header": [
  "model",
  "d"
 ],
 "row_groups": [],
 "header_cells": [
  {
   "value": "model",
   "confidence": "unverified",
   "sources": []
  },
  {
   "value": "d",
   "confidence": "unverified",
   "sources": []
  }
 ],
 "rows": [
  [
   {
    "value": "LB 08",
    "confidence": "unverified",
    "sources": []
   },
   {
    "value": "1432",
    "confidence": "verified",
    "sources": [
     "vision-1",
     "vision-2"
    ]
   }
  ]
 ]
}

header 是純粹的欄名 —— 從 header_cells 導出,絕不另外計算,所以兩者不會漂開。header_cells 是同一組名字加上 confidence 與 sources:欄名錯一個,整欄的意思就變了,而且你光看看不出來。

rows 是列的清單,每列是格子的清單。column_major 告訴你原表是橫著走還是直著走;我們永遠交付列,這個欄位記錄的是頁面上原本的樣子。

row_groups 是規格表上那種旋轉的側邊分類(Dimensions (mm)、Load capacity)—— 每列一個標籤。它不是一欄,因為欄數是交叉比對的根基;但少了它你分不出 C₀ 是負載還是長度。表格沒有分組時為空。

只在適用時才出現的欄位

這些和 unreadable 遵守同一條規則:每張表都帶一個 false 是雜訊,你要掃的是例外。

每張表也帶 bbox —— 整張表在頁面上的外框,座標和格子、散文、影像同樣用 PDF 點(取該表各格子框的聯集;一個格子框都沒有時就不給這個欄位)—— 以及 order,它在該頁閱讀順序中的位置。當版面讀取對一頁有幾張表意見不一時,order 改由 bbox 量出:等於表上方最後一個散文或影像區塊的 order。配合 pages[].width/height,就足以把頁面重建成結構化的版面。

散文與影像

結果不只有 tables。每份文件也帶 prose(連續文字 —— 標題與段落)和 images(裁下的圖)。兩者都用和格子一樣的方式交叉比對,也都會說是誰佐證了它們。

prose

{"page": 7,
 "index": 2,
 "text": "Preload classes are selected according to the rail size.",
 "confidence": "verified",
 "sources": ["ocr-1", "ocr-2"],
 "bbox": [56.2, 98.6, 213.6, 236.9],
 "role": "paragraph",
 "level": 0,
 "order": 4}

每個文字區塊一筆,逐頁編號。role 是 heading 或 paragraph;level 是標題層級(段落為 0);order 是該頁閱讀順序中的位置,與 images 共用,方便你穿插排列。

負責呈現文字的那個讀取,不算作它自己的證人。一個段落是 verified,是因為對這一頁的另一個讀取含有相同內容 —— 所以你看到的來源是同意的那些,絕不是被檢查的那一個。段落邊界不必吻合:各個讀取切分文字的方式不同,那是排版差異,不是不一致。

images

{"page": 7,
 "index": 1,
 "path": "images/p007_00.png",
 "confidence": "verified",
 "bbox": [56.2, 98.6, 213.6, 236.9],
 "order": 3,
 "also_on": [9],
 "sources": ["layout", "ocr", "pdf-image"]}

path 相對於結果包(zip 匯出);also_on 列出帶有位元組完全相同副本的其他頁 —— 重複的會回報,不會移除,因為同一張尺寸圖本來就會合理地出現在兩個料號底下。

影像用自己的一套來源詞彙,因為問題是「這裡有沒有一張圖」,不是「這個值有沒有讀對」。注意什麼不會讓一張圖成為 verified:只有 pdf-image。PDF 在那個位置含有內嵌影像,只說明檔案裡有一張圖,不代表我們框對了 —— 早先的版本把它當成充分條件,結果三份文件回來 100% verified,而「整張圖漏掉」的機率在結構上是零。

pages

[{"page": 6, "width": 612.0, "height": 792.0},
 {"page": 7, "width": 612.0, "height": 792.0, "unreadable": true}]

當你要求的是頁面範圍時,旁邊會有 source_pages:它把交付內容中的位置對應回你原始檔案的頁碼,所以任何結果都能指回它來自的那一頁。

你要求的每一頁一筆。width 與 height 是畫布大小,單位 PDF 點 —— 少了它們,bbox 就沒有可依附的框。

限制

錯誤

一律是 {"detail": "…"},寫給人看 —— 絕不含伺服器路徑、絕不含金鑰名稱。

這裡沒有的

坦白說

掃描檔辨識效果會明顯下降。我們把 PDF 的文字層當成額外的獨立讀取依據；少了它，我們實測的交叉比對覆蓋率降到 1/3–1/18。text_layer 在 202 回應裡就會回報 —— 不必等跑完才知道。

正確率每份文件差很多。怎麼量、樣本多大、哪裡會失敗都有文件記載,並附人工查核的下限。我們不會在這裡籠統寫「99%+」。