API ドキュメント

ひとつのエンドポイント。フォーマットバージョン 4。ベース URL https://api.consensis.app。

認証

すべてのリクエストに API キーを付けます — Authorization: Bearer pk_live_… または X-API-Key ヘッダー。サインイン(Google またはメール。サインインでアカウントが作成されます)して、アカウントページでキーを発行してください。平文のキーは 1 回だけ表示され、当社はダイジェストのみ保存します。照合できないキーは 401 を返します — 打ち間違えたキーが黙って匿名トライアルに降格されることはないので、ジョブがどのアカウントに請求されたかは常に分かります。

無料で試す — キー不要、アカウント不要

無料トライアルは API から直接使えます:1 接続元あたり 1 日 10 ページ無料、Authorization ヘッダーはまったく不要です(Web アップローダーには別枠で 10 ページがあります。枠を超えるとレスポンスに Retry-After が付きます)。

# 完全に匿名 — キー不要、登録不要
curl -X POST https://api.consensis.app/v1/parse -F "[email protected]"
# → 202 {"id": "…", "status": "queued", ...} — 以下と同じ方法でポーリング

3 行で始める

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]}

独立した 2 つの読み取りが一致したので、このセルは 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}

テキストブロックごとに 1 エントリ、ページ単位で番号付け。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 はバイト単位で同一のコピーを持つ他のページを列挙します — 重複は報告し、除去しません。同じ寸法図が 2 つの品番の下に正当に現れるからです。

画像は独自のソース語彙を使います。問いが「この値は正しく読めたか」ではなく「ここに図があるか」だからです。何が画像を verified にしないかに注意:pdf-image 単独です。PDF がその位置に埋め込み画像を持つことは、ファイルに絵があると言っているだけで、正しい枠を切り出したことの裏付けではありません — 以前のバージョンはこれを十分とみなし、3 つのドキュメントが 100% verified で返ってきた一方で、「図をまるごと見落とす」確率は構造的にゼロでした。

pages

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

ページ範囲を指定した場合、その隣に source_pages が付きます:納品物での位置を元ファイルのページ番号に対応付けるので、結果は常に出所のページを指し示せます。

リクエストしたページごとに 1 エントリ。width と height は PDF ポイントでのキャンバスサイズ — これがないと bbox の置き場がありません。

制限

エラー

常に {"detail": "…"}、人間向けに書かれています — サーバーパスもキー名も決して含みません。

ないもの

正直なところ

スキャンPDFでは精度が著しく低下します。 PDFのテキストレイヤーを独立した追加情報として読み取りに利用しているため、テキストレイヤーがない場合、当社の実測でクロスチェックのカバー率が 1/3〜1/18 に低下します。text_layer の有無は 202 レスポンスで返されるため、処理完了を待たずに確認できます。

精度はドキュメントによって大きく変わります。 測定方法、サンプル数、失敗する箇所は、人手で確認した下限値とともに文書化しています。ここに一律の「99%+」は書きません。