ドキュメント

ドキュメントは、処理された1ページ（アップロードされた画像、またはアップロードされたPDFからレンダリングされた1ページ）です。各ドキュメントはバッチ（batch_nameで識別）に属し、実際に処理を開始する単位となります。マルチページPDFをアップロードすると、同じバッチ内にページごとに1つのドキュメントが作成されます。詳細は以下のドキュメントをアップロードを参照してください。

ドキュメントをアップロード

単一ファイル（画像またはPDF）をバッチにアップロードします。batch_nameを省略すると、自動生成されレスポンスで返されます。アップロードしても抽出は開始されません。一緒に処理したいすべてのファイルをアップロードしたら、バッチの処理を開始を呼び出してください。レスポンスのremaining_batch_capacityは、このバッチがプランの最大バッチサイズ（アカウントのmax_batch_sizeを参照）に達するまでに、あと何件のドキュメントを受け入れられるかを示します。これにより、別途ルックアップを行うことなく、クライアント側でこのバッチに追加を続けるか新しいバッチを開始するかを判断できます。

POST /api/v1/documents

パラメータ

名前	場所	型	説明
`file`	body (multipart)	file	`url`が指定されない場合に必須。画像（JPEG/PNG等）またはPDF。PDFはアップロード1回につき最大30ページまでで、1ページごとに1つのドキュメントに分割されます。
`url`	body (multipart)	string, optional	`file`の代替 — ファイルを直接添付する代わりに、サーバーがこのURLからファイルをダウンロードします。`file`とは排他的で、どちらか一方のみを指定してください。公開された`http://`または`https://`のURLである必要があります（localhost/プライベートネットワークアドレスは不可）。ダウンロードは30MB、15秒の読み取りタイムアウトに制限されています。
`batch_name`	body (multipart)	string, optional	このドキュメントを追加するバッチ。省略すると新しいバッチ名が自動生成され（レスポンスで返されます）、複数のアップロードで同じ値を再利用して、処理前に1つのバッチを構築できます。
`template_id`	body (multipart)	integer, optional	アカウントに紐づくテンプレートIDで、このドキュメントに事前に関連付けます。必須ではありません — `process`を呼び出す際にテンプレート（またはアドホックなフィールド）を渡すこともできます。
`password`	body (multipart)	string, optional	PDFのみ。ファイルがパスワード保護されている場合に最初に試行されます。省略された場合、またはファイルを開けない場合は、アカウントのEmail Inbox設定に保存されている既存のパスワードにフォールバックします。このフィールドはEmail Inboxの設定がなくても使用でき、呼び出しごとの代替手段として機能します。
`Idempotency-Key`	header, optional	string	安全に再試行できます。冪等性を参照してください。

PDFアップロードは単一のIDではなく配列を返します。 PDFをアップロードすると、各ページが個別のドキュメントとしてレンダリングされ、レスポンスのdocument_idはJSON配列（ページ順に1ページにつき1つの文字列）になり、page_countフィールドも追加されます。単一の画像アップロードではスカラー文字列が返されます。document_idが常に文字列であると想定するクライアントコードは、PDFアップロードで動作しなくなります — 送信するファイルがPDFかどうかを確認し、レスポンスの形式に応じて分岐するか、常に画像を送信してスカラーケースに依存しないようにしてください。右側の2つのレスポンス例を参照してください。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
missing_parameter — fileとurlのどちらも送信されていません。
invalid_parameter (param: "file") — 画像またはPDFが無効または破損している、パスワード保護されたPDFをロック解除できなかった（passwordフィールドも保存済みのEmail Inboxパスワードも機能しなかった）、またはPDFが30ページの上限を超えています。
invalid_parameter (param: "url") — fileとurlの両方が送信された、URLが公開アドレスに解決されない、ダウンロードが失敗またはタイムアウトした、またはダウンロードしたファイルが30MBを超えています。
invalid_parameter (param: "batch_name") — バッチがすでにプランの最大バッチサイズに達しています。
invalid_parameter (param: "template_id") または template_not_found。
rate_limit_exceeded — アカウントに未処理（キュー状態）のドキュメントが多すぎます。先にいくつか処理するか削除してください。

ドキュメントの取得

単一のドキュメントの現在のステータスと、抽出が成功した後の再整形されたline_itemsを取得します。これはバッチ結果の取得の単一ドキュメント版です。同じ再整形ルールが適用されますが、?include=bboxオプションはありません（これはバッチレベルの結果エンドポイントのみで使用できます）。

GET /api/v1/documents/{document_id}

パラメータ

名前	場所	型	説明
`document_id`	パス	文字列	`POST /documents`で返されたドキュメントID（PDFページの場合は、その配列の1つのエントリ）。

statusは常にqueued、processing、succeeded、failed、canceledのいずれかです。ステートマシンについては非同期モデルガイドを参照してください。completed_atは、ドキュメントが最終状態（succeeded、failed、またはcanceled）に達すると設定され、それ以前はnullのままです。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
document_not_found — アカウントにこのIDのドキュメントが存在しません。

ドキュメント画像の取得

ドキュメントのページ画像を返します。デフォルトでは全ページ、または?crop=で指定された正規化された切り抜き領域を返します。これは、純粋な位置情報フィールドのimage_urlを実現する機能です（バッチ結果の取得を参照）。独自の座標で直接呼び出すこともできます。

GET /api/v1/documents/{document_id}/image

パラメータ

名前	場所	型	説明
`document_id`	path	string	ドキュメントID。
`crop`	query, optional	string	`"x1,y1,x2,y2"` — 0から1の間の4つの浮動小数点数。API内の他のすべての`bbox`オブジェクトと同じ正規化座標規則に従います。省略すると、切り抜きなしの全ページ画像を取得します。

レスポンスは生の画像バイト列（Content-Type: image/jpeg）であり、JSONではありません。このエンドポイントの右側にはレスポンスJSONの例はなく、リクエストのみが表示されます。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
document_not_found — このIDのドキュメントがないか、元の画像ファイルが利用できなくなりました（例：アカウントの自動削除保存期間を過ぎた場合）。
invalid_parameter (param: "crop") — crop値の形式が不正、座標が0～1の範囲外、または画像境界にクリップした結果、切り抜き領域が空になっています。

bboxアノテーションのトリガー

抽出された各フィールドの値がページ上のどこに物理的に位置するかを特定する、オプションの有料の2回目のジョブを明示的に開始します。これは抽出自体とは別の課金対象アクションです。これを組み込む前に、Bounding Boxesガイド（特に、アカウントのauto_annotate_bbox設定により、このエンドポイントを呼び出さなくても同じジョブが自動的にトリガー（および課金）される可能性があるという注意事項）を参照してください。

POST /api/v1/documents/{document_id}/bbox

パラメータ

名前	場所	型	説明
`document_id`	path	string	抽出データが存在する`succeeded`状態のドキュメントである必要があります。抽出が完了していないドキュメントにはアノテーションを付与できません。
`Idempotency-Key`	header, optional	string	推奨 — このアクションはクレジットを消費します。冪等性を参照してください。

新しいbboxジョブがエンキューされたばかりの場合は202を、このドキュメントに対するbboxジョブがすでに実行中であった場合（already_running: true）は200を返します。これは、以前に同じエンドポイントをこのドキュメントに対して呼び出しており、その以前のbboxジョブがまだ完了していないことを意味します。これは、ドキュメント自体の抽出が完了しているかどうかとは無関係です。bboxは、すでにsucceeded状態のドキュメントに対してのみトリガーできます（以下の「考えられるエラー」を参照）。そのため、このエンドポイントを呼び出せる時点では、抽出は完了しています。already_runningは、抽出ジョブではなく、同じドキュメントに対する2回目のbboxジョブに関するものです。いずれの場合（202または200）でも、200のパスでは新しい処理は開始されず、課金もされません。結果を取得するには、返されたgroup_batch_idを使用してbboxアノテーションの取得をポーリングしてください。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
document_not_found — このIDのドキュメントがアカウントに存在しません。
insufficient_credits — このアノテーションパスを実行するためのクレジットが不足しています。
invalid_parameter — ドキュメントがまだこの処理を実行できる状態ではありません（処理中であるか、ボックスを配置するための抽出データがありません）。

bboxアノテーションの取得

ドキュメントに対してトリガーされた最新のbboxアノテーションジョブのステータスをポーリングし、結果を取得します。このドキュメントに対してジョブが一度もトリガーされていない場合、existsはfalse、status/group_batch_idはnullになります。これは正常で一般的なレスポンスであり（ほとんどのドキュメントではbboxはトリガーされません）、エラーではありません。

GET /api/v1/documents/{document_id}/bbox

パラメータ

名前	場所	型	説明
`document_id`	path	string	ドキュメントID。

rowsは、行インデックス（文字列、例："0"）を、フィールド名から正規化されたbboxオブジェクト（または、そのフィールドの位置がページ上で見つからなかった場合はnull）へのマップにマッピングします。statusは、APIの他の場所と同じクローズドな5値の列挙型を使用します。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
document_not_found — このIDのドキュメントがアカウントに存在しません。

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, files={"file": open("invoice.jpg", "rb")}, data={"batch_name": "july-invoices"}, ) print(response.json())

import { readFile } from "node:fs/promises"; const formData = new FormData(); formData.append("file", new Blob([await readFile("invoice.jpg")]), "invoice.jpg"); formData.append("batch_name", "july-invoices"); const response = await fetch("https://imagetotable.ai/api/v1/documents", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, body: formData, }); console.log(await response.json());

curl -X POST https://imagetotable.ai/api/v1/documents \ -H "Authorization: Bearer $API_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -F "url=https://imagetotable.ai/static/samples/invoice.webp" \ -F "batch_name=july-invoices"

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, data={ "url": "https://imagetotable.ai/static/samples/invoice.webp", "batch_name": "july-invoices", }, ) print(response.json())

{ "document_id": [ "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p1", "8f14e45f-ceea-467e-9de1-a3e9c93a9c95_p2" ], "batch_name": "july-invoices", "page_count": 2, "remaining_batch_capacity": 198 }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "batch_name": "july-invoices", "filename": "invoice_042.jpg", "status": "succeeded", "created_at": "2026-07-16T09:12:03+00:00", "started_at": "2026-07-16T09:12:05+00:00", "completed_at": "2026-07-16T09:12:14+00:00", "line_items": [ { "invoice_number": "INV-1042", "invoice_date": "2026-07-01", "total_amount": "1,204.50" } ] }

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) with open("page.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("page.jpg", Buffer.from(await response.arrayBuffer()));

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, params={"crop": "0.10,0.08,0.42,0.30"}, ) with open("crop.jpg", "wb") as f: f.write(response.content)

import { writeFile } from "node:fs/promises"; const url = new URL("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image"); url.searchParams.set("crop", "0.10,0.08,0.42,0.30"); const response = await fetch(url, { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); await writeFile("crop.jpg", Buffer.from(await response.arrayBuffer()));

import os import uuid import requests response = requests.post( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={ "Authorization": f"Bearer {os.environ['API_KEY']}", "Idempotency-Key": str(uuid.uuid4()), }, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { method: "POST", headers: { "Authorization": `Bearer ${process.env.API_KEY}`, "Idempotency-Key": crypto.randomUUID(), }, }); console.log(await response.json());

import os import requests response = requests.get( "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", headers={"Authorization": f"Bearer {os.environ['API_KEY']}"}, ) print(response.json())

const response = await fetch("https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox", { headers: { "Authorization": `Bearer ${process.env.API_KEY}` }, }); console.log(await response.json());

{ "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95", "exists": true, "status": "succeeded", "group_batch_id": "bx_8a3c2e1f", "rows": { "0": { "invoice_number": {"x1": 0.121, "y1": 0.084, "x2": 0.418, "y2": 0.112, "unit": "normalized"}, "total_amount": null } } }