API 文档

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

认证

每个请求都带 API 密钥 —— Authorization: Bearer pk_live_… 或 X-API-Key 头。登录（Google 或邮箱，登录即创建账户）后在账户页签发密钥。明文密钥只显示一次；我们只保存摘要。无法匹配的密钥返回 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 是规格表上您看到的旋转侧向分类（尺寸 (mm)、载荷）—— 每行一个标签。它不是一列，因为列数是交叉比对的基础，但没有它您就分不清 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%+”。