バッチ

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

バッチの処理を開始する

現在バッチ内にあるすべての対象ドキュメント（すでにprocessingまたはsucceeded状態のものを除く）に対して抽出を開始します。このエンドポイントが実際にクレジットを消費する場所です。アカウントがStandardモデルティアの場合、キューに入ったドキュメントごとに1クレジット消費されます。これはすべてのアカウントが初期状態で設定されているデフォルトです。アカウントにAdvancedまたはPremiumが割り当てられている場合は、各ドキュメントのコストはそれぞれ3または6クレジットになります。ティアによって実行される抽出モデルが変わるだけで、返されるフィールドやレスポンスの形式は変わらないため、このエンドポイントの契約内容に他の変更はありません。このリクエストにはtierパラメータはありません。モデルティアはImageToTable.aiチームが割り当てるアカウントレベルの設定であり、呼び出し側がバッチごとに選択するものではありません。このエンドポイントが呼び出された時点で有効なティアが課金対象となり、処理が完了する前にアカウントのティアが変更された場合でも、ここでキューに入ったドキュメントにはそのティアが固定されます。複数のprocess呼び出しにまたがるバッチでは、その間にアカウントのティアが変更された場合、異なるドキュメントが異なるティアで課金される可能性があります。アカウント設定とAPIの動作で完全な設定表を、アカウント使用状況で非Standardティアの控除がクレジット台帳でどのように表示されるかをご確認ください。

パラメータ

qualityは、APIが呼び出しごとに上書きできる唯一のアカウント設定です — その他の アカウントレベルの設定（bbox自動アノテーション、保持ポリシー）はアカウントから読み取られ、リクエストごとに上書きすることはできません。 詳細はアカウント設定とAPIの 動作を参照してください。auto_annotate_bboxが、そのエンドポイントを呼び出していなくても、この呼び出しがbboxアノテーションに対しても課金される可能性がある理由も含めて説明しています。

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

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

発生しうるエラー

• 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）。特定バッチのドキュメント単位の完全なデータは、バッチ結果の取得を参照してください。

パラメータ

考えられるエラー

• missing_api_key / invalid_api_key / plan_required — エラー処理を参照してください。
• invalid_parameter — mode、limit、status、またはpage_tokenが不正です。

バッチステータスの取得

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

パラメータ

考えられるエラー

• missing_api_key / invalid_api_key / plan_required — エラー処理を参照してください。
• batch_not_found

バッチ結果の取得

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

パラメータ

?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スケールでもありません。精度に関する注意点はBounding Boxesガイドを参照してください。これらの座標はモデルから直接取得され、ピクセルレベルの検証処理は行われないため、密度の高い文書や複雑な文書では「正確」ではなく「近似」として扱ってください。

発生しうるエラー

• missing_api_key / invalid_api_key / plan_required — Error Handlingを参照してください。
• batch_not_found

バッチをエクスポート

便利なダウンロード機能です。上記のresultsはこのAPIが中心に構築されている正規の構造化形式ですが、このエンドポイントは、リシェイプコードを自分で書かずに同じデータをスプレッドシートに取り込むために存在します。xlsxのみ対応です。v1はテーブル（抽出）モードのみをサポートしており、メインアプリでのWord（docx）エクスポートはpage_wordモードのネイティブ出力（まったく異なるプロンプトと結果形式）に限定され、v1では公開されていません。「テーブルデータをWord文書として出力」するオプションはここにはありません。知っておくべき動作の違いが1つあります。バッチのテンプレートにMulti-Page Mergeが設定されている場合、このエンドポイントは常にそれを適用します。resultsとは異なり、ここにはオプトアウト用のクエリパラメータはありません。スプレッドシートのダウンロードには、既存の統合との互換性を維持する必要がないためです。

パラメータ

レスポンスはファイルのダウンロード（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アノテーションジョブも削除されます。

パラメータ

発生しうるエラー

• missing_api_key / invalid_api_key / plan_required — エラーハンドリングを参照してください。
• batch_not_found — 他のリソースとは異なり、所有していない（または存在しない）batch_nameを削除した場合、ここでは黙って何もしないのではなく404が返ります。