# Documents API リファレンス — アップロード、ステータス、bbox

> ドキュメントや画像をアップロードし、抽出ステータスを確認し、ページ画像や正規化された切り抜きを取得し、ImageToTable.ai v1 API のオプションのバウンディングボックス位置情報をトリガーします。

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

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

単一ファイル（画像またはPDF）をバッチにアップロードします。`batch_name`を省略すると、自動生成されレスポンスで返されます。アップロードしても抽出は開始されません。一緒に処理したいすべてのファイルをアップロードしたら、[バッチの処理を開始](/developers/reference/batches#start-processing-a-batch)を呼び出してください。レスポンスの`remaining_batch_capacity`は、このバッチがプランの最大バッチサイズ（[アカウント](/developers/reference/account)の`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` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `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`を取得します。これは[バッチ結果の取得](/developers/reference/batches#get-batch-results)の単一ドキュメント版です。同じ再整形ルールが適用されますが、`?include=bbox`オプションはありません（これはバッチレベルの結果エンドポイントのみで使用できます）。

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

### パラメータ

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

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

### 発生しうるエラー

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

## ドキュメント画像の取得

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

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

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

抽出された各フィールドの値がページ上のどこに物理的に位置するかを特定する、オプションの**有料**の2回目のジョブを明示的に開始します。これは抽出自体とは別の課金対象アクションです。これを組み込む前に、[Bounding Boxes](/developers/guides/bbox)ガイド（特に、アカウントの`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アノテーションの取得](#get-bbox-annotation)をポーリングしてください。

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `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` — [エラーハンドリング](/developers/guides/errors)を参照してください。
- `document_not_found` — このIDのドキュメントがアカウントに存在しません。

## Code Examples

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

POST /api/v1/documents

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/documents \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@invoice.jpg" \
  -F "batch_name=july-invoices"
```

**Python**

```python
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())
```

**Javascript**

```javascript
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());
```

### ドキュメントをアップロード — URLから

POST /api/v1/documents

ローカルファイルは不要です。この例はそのまま実行可能です。`invoice.webp`は当サイトでホストしている実際のファイルです。

**cURL**

```bash
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"
```

**Python**

```python
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())
```

**Javascript**

```javascript
const formData = new FormData();
formData.append("url", "https://imagetotable.ai/static/samples/invoice.webp");
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());
```

### レスポンス — 単一画像

```json
{
  "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
  "batch_name": "july-invoices",
  "remaining_batch_capacity": 199
}
```

### レスポンス — マルチページPDF

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

### ドキュメントを取得

GET /api/v1/documents/{document_id}

**cURL**

```bash
curl https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95 \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
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())
```

**Javascript**

```javascript
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());
```

### レスポンス

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

### ドキュメント画像の取得 — 全ページ

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

**cURL**

```bash
curl https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image \
  -H "Authorization: Bearer $API_KEY" \
  -o page.jpg
```

**Python**

```python
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)
```

**Javascript**

```javascript
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()));
```

### ドキュメント画像の取得 — 切り抜き

GET /api/v1/documents/{document_id}/image?crop=...

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image?crop=0.10,0.08,0.42,0.30" \
  -H "Authorization: Bearer $API_KEY" \
  -o crop.jpg
```

**Python**

```python
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)
```

**Javascript**

```javascript
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()));
```

### bboxアノテーションをトリガー

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

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

**Python**

```python
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())
```

**Javascript**

```javascript
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());
```

### レスポンス — 202, 新規ジョブ

```json
{
  "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
  "group_batch_id": "bx_8a3c2e1f",
  "status": "queued",
  "already_running": false,
  "row_groups": 1
}
```

### レスポンス — 200, 既に実行中

```json
{
  "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
  "group_batch_id": "bx_8a3c2e1f",
  "status": "processing",
  "already_running": true,
  "row_groups": 1
}
```

新しい処理は開始されておらず、課金も発生しません。このドキュメントに対する同一エンドポイントへの以前の呼び出しで、既にジョブが実行中です。同じ`group_batch_id`を使用して[bboxアノテーションの取得](#get-bbox-annotation)をポーリングしてください。

### bboxアノテーションの取得

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

**cURL**

```bash
curl https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/bbox \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
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())
```

**Javascript**

```javascript
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());
```

### レスポンス

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

---

Source: https://imagetotable.ai/ja/developers/reference/documents