# APIクイックスタート — 5分で結果を取得

> ImageToTable.ai v1 APIの5分間のエンドツーエンドウォークスルー：キー取得、請求書アップロード、処理開始、抽出したJSONの取得までを解説します。

ここでは、キーの取得、ドキュメントのアップロード、処理の開始、結果の取得までの一連の流れを、請求書を例に説明します。まだ`curl`をインストールしていない場合や、キーの環境変数を設定していない場合は、先に[環境設定](/developers/environment-setup)をご覧ください。

## ステップ1 — APIキーを取得する

APIキーは、アカウントの[プロフィール設定ページ](/profile/)の「API Key」にあります。v1 APIを使用するには、有料プラン（Basic以上）が必要です。Freeプランのキーは認証チェックを通過しますが、その後のすべての呼び出しで`plan_required`エラーが返されます。今後生成されるキーは`itt_live_<64文字の16進数>`の形式になります。スクリプトにハードコードしないよう、環境変数としてエクスポートしてください。

```bash
export API_KEY="itt_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

## ステップ2 — ドキュメントをアップロードする

`POST /api/v1/documents`は、`file`（マルチパート）またはサーバーが取得する`url`のいずれかを受け取ります。どちらか一方のみを渡してください。`batch_name`はオプションです。省略するとAPIが自動生成します（レスポンスで返されます）。一緒に処理したいドキュメントはすべて同じ`batch_name`を共有する必要があります。この例では、当サイトでホストされている実際のサンプル請求書に対して`url`を使用しているため、ローカルファイルを必要とせず、そのまま実行できます。

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/documents \
  -H "Authorization: Bearer $API_KEY" \
  -F "url=https://imagetotable.ai/static/samples/invoice.webp"
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/documents",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    data={"url": "https://imagetotable.ai/static/samples/invoice.webp"},
)
print(response.json())
```

**Javascript**

```javascript
const formData = new FormData();
formData.append("url", "https://imagetotable.ai/static/samples/invoice.webp");

const response = await fetch("https://imagetotable.ai/api/v1/documents", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
  body: formData,
});
console.log(await response.json());
```

代わりにローカルファイルをお持ちですか？`url`をマルチパートの`file`フィールドに置き換えてください。`batch_name`、`template_id`、`password`を含む全パラメータのリストは、リファレンスの[ドキュメントをアップロードする](/developers/reference/documents#upload-a-document)をご覧ください。

レスポンスは新しいドキュメントのIDと、それが属するバッチを返します。`batch_name`は保存しておいてください。次の2つのステップで必要になります。

```json
{
  "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
  "batch_name": "260716-4K9P",
  "remaining_batch_capacity": 199
}
```

画像の代わりにマルチページPDFをアップロードする場合も同様に動作します。ただし、各ページは独立して処理されるため、`document_id`は*配列*（ページごとに1つのドキュメント）として返されます。

## ステップ3 — 処理を開始する

`POST /api/v1/batches/{batch_name}/process`で抽出を開始します。保存済みの[テンプレート](/developers/reference/templates-fields)を`template_id`で指定するか、今回のように`fields`で抽出したいフィールドを直接宣言して1回限りの実行も可能です。

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/260716-4K9P/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          {"name": "invoice_number"},
          {"name": "invoice_date"},
          {"name": "vendor_name"},
          {"name": "total_amount"}
        ]
      }'
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/process",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    json={
        "fields": [
            {"name": "invoice_number"},
            {"name": "invoice_date"},
            {"name": "vendor_name"},
            {"name": "total_amount"},
        ]
    },
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      { name: "invoice_number" },
      { name: "invoice_date" },
      { name: "vendor_name" },
      { name: "total_amount" },
    ],
  }),
});
console.log(await response.json());
```

これにより、クレジットが即座に消費され（1回の呼び出しにつき1ドキュメント分）、ドキュメントがバックグラウンド処理のためにキューに入れられます。

```json
{
  "batch_name": "260716-4K9P",
  "queued": 1,
  "quality": "fast",
  "webhook_registered": false
}
```

`fields`と`template_id`を完全に省略すると、APIが自動的に適切なカラム名を推論します。`quality`もオプションです。省略した場合、処理はアカウントの速度/品質設定（[アカウント設定とAPIの動作](/developers/guides/account-settings)を参照）にフォールバックします。ここでの`webhook_registered: false`は、この特定の呼び出しに`webhook_url`が含まれていなかったことを意味するだけで、このバッチにwebhookが登録されていないことを意味するわけではありません。`PUT .../webhook`で個別に登録する場合は、[バッチリファレンス](/developers/reference/batches#start-processing-a-batch)を参照してください。

## ステップ4 — 結果を取得する

処理は非同期で行われます。`GET /api/v1/batches/{batch_name}` をポーリングして `all_done` が `true` になるまで待つか（単一ドキュメントなら数秒）、ポーリングの代わりに [webhook](/developers/guides/webhooks) を登録してください。完全なライフサイクルは [Async Task Model](/developers/guides/async-model) ガイドで説明しています。

完了したら、整形された結果を取得します。

**cURL**

```bash
curl https://imagetotable.ai/api/v1/batches/260716-4K9P/results \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches/260716-4K9P/results",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/260716-4K9P/results", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

レスポンスJSONは言語タブで切り替わりません。どのクライアントがリクエストを送信しても構造は変わりません。

```json
{
  "batch_name": "260716-4K9P",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03Z",
  "started_at": "2026-07-16T09:12:05Z",
  "completed_at": "2026-07-16T09:12:14Z",
  "documents": [
    {
      "document_id": "3f9c9e2a-1b7d-4e2b-9a3e-2f5b6c7d8e9f",
      "filename": "invoice.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03Z",
      "started_at": "2026-07-16T09:12:05Z",
      "completed_at": "2026-07-16T09:12:14Z",
      "line_items": [
        {
          "invoice_number": "INV-1042",
          "invoice_date": "2026-06-30",
          "vendor_name": "Acme Supply Co.",
          "total_amount": "1,284.50"
        }
      ]
    }
  ]
}
```

`completed_at` は、ドキュメント（またはバッチレベルではバッチ内のすべてのドキュメント）が `succeeded`、`failed`、`canceled` のいずれかの終了状態に達すると設定されます。`queued` または `processing` の間は `null` のままです。また、バッチレベルでは、一部のドキュメントが先に終了しても、 バッチ内の*すべて*のドキュメントが完了するまで `null` のままです。

## 次のステップ

ここからは、[非同期タスクモデル](/developers/guides/async-model)で完全なステータスライフサイクルを、[Webhooks](/developers/guides/webhooks)でポーリングに代わる通知方法を、[APIリファレンス](/developers/reference/)ですべてのエンドポイントの完全なパラメータリストをご確認ください。

---

Source: https://imagetotable.ai/ja/developers/quickstart