バッチ

バッチとは、1つ以上のドキュメントをグループ化し、まとめて処理、ステータス確認、結果取得を行うための名前付きグループです。バッチを明示的に作成する必要はありません。ドキュメントをbatch_nameを指定してアップロードすると（ドキュメントのアップロードを参照）、初回アップロード時に暗黙的に作成されます。

バッチの処理を開始する

現在バッチ内にあるすべての対象ドキュメント（processingまたはsucceeded状態でないもの）の抽出を開始します。このエンドポイントで実際にクレジットが消費されます（キューに入ったドキュメント1件につき1クレジット）。

POST /api/v1/batches/{batch_name}/process

パラメータ

名前	場所	型	説明
`batch_name`	path	string	処理するバッチ名。
`template_id`	body (JSON)	integer, 省略可	適用する保存済みテンプレート。`fields`と両方指定された場合はこちらが優先されます。
`fields`	body (JSON)	array, 省略可	この実行のみに使用するアドホックなフィールドリスト。`[{"name": "...", "format_requirement": "..."}]`またはフィールド名の文字列配列。`template_id`が指定された場合は無視されます。両方を省略すると、モデルが自動的に列を推論します。
`quality`	body (JSON)	string, 省略可	`"fast"`または`"high"`。省略すると、アカウントの`thinking_type`設定が適用されます。アカウント設定とAPIの動作を参照してください。
`webhook_url`	body (JSON)	string, 省略可	このバッチの完了コールバックを同じ呼び出しで登録（または更新）します。バッチWebhookの登録と同等です。`http://`または`https://`である必要があります。
`Idempotency-Key`	header, 省略可	string	強く推奨 — このエンドポイントはクレジットを消費します。冪等性を参照してください。

quality は、API が呼び出しごとに上書きできる唯一のアカウント設定です。その他のアカウントレベルの設定（bbox 自動注釈、保持ポリシー）はアカウントから読み取られ、リクエストごとに上書きすることはできません。詳細はアカウント設定とAPIの動作をご覧ください。この中では、auto_annotate_bbox が、そのエンドポイントを呼び出していなくても、この呼び出しで bbox 注釈の料金が発生する理由についても説明しています。

レスポンスの webhook_registered は、この特定の呼び出しのみを反映します — このリクエストに webhook_url が含まれていた場合にのみ true となり、バッチに Webhook が設定されているかどうかは関係ありません。以前にバッチWebhookの登録で Webhook が設定され（ここでは繰り返されていない）、完了時にコールバックが正しく実行されるバッチでも、このフィールドはその呼び出しでは false を返します。既存の BatchWebhook があるかどうかを確認することはありません。ここで false が返されても、「このバッチでは Webhook が実行されない」と判断しないでください。

すでに処理して通知を受け取ったバッチに対して、さらにドキュメントをアップロードした後に、このエンドポイントを再度呼び出すと、そのバッチの Webhook がすでに実行されていた場合、自動的に再設定され、新しい波の完了時にも通知が行われます。これを実現するために追加の呼び出しは必要ありません。正確なセマンティクス（2つの波が重なった場合の動作を含む）については、Webhookガイドの「バッチの再処理」セクションを参照してください。

発生する可能性のあるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
batch_not_found — お客様のアカウントに、この batch_name のドキュメントが存在しません。
invalid_parameter — quality/webhook_url/template_id の値が不正であるか、バッチ内に現在処理可能なドキュメントがありません（すべて完了済み/処理中、またはバッチが空です）。
template_not_found
insufficient_credits — キューに入れようとしているドキュメントをカバーするのに十分なクレジットがありません。

バッチ一覧

バッチのページネーション対応・フィルタ可能な要約リストを返します。API利用者向けの「Files Filter」相当の機能です。ここでは要約（document_count、集計status）のみを返します。特定バッチの完全なドキュメント単位データを取得するにはバッチ結果の取得を使用してください。

GET /api/v1/batches

パラメータ

名前	場所	型	説明
`source`	query, オプション	string	`direct`、`collect`、`email_inbox`、`api`（メインWebアプリの`direct`とは別に`POST /documents`でアップロード）、または`share`（`collect`と`email_inbox`の両方をカバーするエイリアス）のいずれか。省略すると全ソースが対象になります。
`q`	query, オプション	string	バッチ内のファイル名に対する大文字小文字を区別しない部分一致検索。
`date_from`	query, オプション	string (`YYYY-MM-DD`)	アップロード時刻の下限（指定日を含む）。
`date_to`	query, オプション	string (`YYYY-MM-DD`)	アップロード時刻の上限（指定日の終了時を含む）。
`status`	query, オプション	string	フィルタする公開ステータス（`queued,processing,succeeded,failed,canceled`）のカンマ区切りリスト。
`template_id`	query, オプション	integer	このテンプレートを使用したバッチのみ。
`mode`	query, オプション	string	現時点で受け付け可能な値は`"table"`のみです（v1が現在サポートする唯一のモード）。将来の抽出モード用に予約されています。
`limit`	query, オプション	integer	1～100。デフォルトは20。
`page_token`	query, オプション	string	前回のレスポンスの`next_page_token`から取得する不透明なカーソル。詳細はページネーションを参照してください。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — 詳細はエラーハンドリングをご覧ください。
invalid_parameter — mode、limit、status、またはpage_tokenが不正です。

バッチステータスの取得

1つのバッチに対する軽量な集計ステータスです。公開ステータスごとの件数とall_doneフラグを返します。完全な結果ペイロードがまだ不要な、安価なポーリングループに便利です。

GET /api/v1/batches/{batch_name}

パラメータ

名前	場所	型	説明
`batch_name`	path	string	確認するバッチを指定します。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — 詳細はエラーハンドリングをご覧ください。
batch_not_found

バッチ結果の取得

抽出データを取得する主要な方法です。バッチ内のすべてのドキュメントが、再構成されたline_items（抽出された行ごとに{field_name: value}オブジェクトの配列）とともに返されます。フィールドレベルの値は、デフォルトでは単なるスカラー値（文字列、数値など）です。

GET /api/v1/batches/{batch_name}/results

パラメータ

名前	場所	型	説明
`batch_name`	path	string	結果を取得するバッチを指定します。
`include`	query, optional	string	`"bbox"` — 設定すると、すべてのフィールド値が単なるスカラー値ではなく`{"value": ..., "bbox": {...}\|null}`になり、各ドキュメントに`bbox_status`フィールドが追加されます。以下の注意事項をご参照ください。これは新しいbboxジョブを決してトリガーせず、すでに計算済みのもののみを返します。

?include=bboxは、バックフィルされた結果のみを読み取ります。つまり、bboxアノテーションのトリガーを代わりに実行することはありません。ドキュメントに対してbboxが一度もトリガーされていない場合（手動、またはアカウントのauto_annotate_bbox設定による場合）、そのドキュメントのフィールドは単に"bbox": nullとして返されます。

位置情報のみのフィールドは、これらとは異なる第3の形状です。一部のテンプレートフィールドは、テキストを書き写すのではなく、何かを特定するようモデルに指示します（例：「ポートレート写真の位置を特定する」）。これらのフィールドでは、値全体が位置情報です。そのため、スカラー値や上記の{"value","bbox"}ペアの代わりに、{"type": "image_region", "bbox": {...}, "image_url": "..."}が返されます。これは?include=bboxが設定されているかどうかに関係なく行われます。ここでのボックスはオプションのメタデータではなく、フィールドの唯一の内容です。image_urlは、すぐに取得可能な切り抜きJPEG画像を指します（ドキュメント画像の取得を参照）。そのため、4つの数値から元の画像を自分で切り抜く必要はありません。

すべての bbox オブジェクトは、形状に関わらず "unit": "normalized" を使用します。座標はページの幅・高さに対する0から1の浮動小数点数であり、ピクセルや0～1000のスケールではありません。精度に関する注意事項については、バウンディングボックスガイドを参照してください。これらの座標はモデルから直接取得され、ピクセルレベルの検証は行われていません。そのため、密度の高い文書や複雑な文書では「正確」ではなく「近い」値として扱ってください。

考えられるエラー

missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
batch_not_found

バッチのエクスポート

便利なダウンロード機能です。上記の results は、このAPIが基盤とする正規の構造化フォーマットです。このエンドポイントは、自分で整形コードを書かずに同じデータをスプレッドシートに取り込むために存在します。xlsxのみ対応しています。v1はテーブル（抽出）モードのみをサポートし、メインアプリでのWord（docx）エクスポートは、専らpage_wordモードのネイティブ出力（まったく異なるプロンプトと結果形状）であり、v1では公開されていません。ここでは「Word文書としてのテーブルデータ」オプションはありません。

GET /api/v1/batches/{batch_name}/export

パラメータ

名前	場所	型	説明
`batch_name`	パス	文字列	エクスポートするバッチ。
`format`	クエリ（オプション）	文字列	`xlsx`（デフォルト）のみ受け付けます。

レスポンスはファイルダウンロード（Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet）であり、JSONではありません。このエンドポイントにはレスポンスJSONの例はありません。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラー処理をご覧ください。
batch_not_found
invalid_parameter (param: "format") — xlsx以外の値が指定された場合。

バッチを削除する

バッチ内のすべてのドキュメントを完全に削除します。削除前に、queued状態のドキュメントは返金されます。また、バッチのWebhook登録（存在する場合）と、そのドキュメントに関連するbboxアノテーションジョブも削除されます。

DELETE /api/v1/batches/{batch_name}

パラメータ

名前	場所	型	説明
`batch_name`	path	string	削除するバッチを指定します。

発生しうるエラー

missing_api_key / invalid_api_key / plan_required — エラー処理をご覧ください。
batch_not_found — 他のリソースとは異なり、所有していない（または存在しない）batch_nameを削除しようとすると、ここではエラーを返さずに無視するのではなく、404エラーが発生します。