# 手書きから Excel

手書き向けに最適化された認識処理で、手書きの表、日誌、記録を編集可能な XLSX ブックに変換します。

公式ドキュメント: https://img2excel.net/ja/docs/api/handwriting-to-excel

`POST /api/v1/handwriting-to-excel`

手書き向けに最適化された認識処理で、手書きの表、日誌、記録を編集可能な XLSX ブックに変換します。この同期エンドポイントは、変換が完了するまで待機します。変換失敗時にはクレジットを消費しません。

表全体が写った、鮮明で明るさが均一な画像を使用してください。ブックを利用する前に、認識された名前、日付、数値を確認してください。

## リクエスト

### リクエストヘッダー

| ヘッダー | 必須 | 説明 |
| --- | --- | --- |
| `Authorization` | はい | `Bearer $IMG2EXCEL_API_KEY`。サーバー側の API キーを使用します。 |
| `Content-Type` | はい | boundary を含む `multipart/form-data`。ファイル送信時は HTTP クライアントに自動設定させてください。 |
| `Idempotency-Key` | いいえ | 同じリクエストの重複処理を防ぐ冪等キー。最大 200 文字。同じアップロードの再試行には同じ値を使用します。 |

### リクエストボディ

| フィールド | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `file` | バイナリファイル | はい | PNG、JPG、JPEG 画像 1 枚、最大 4MB。 |

画像はファイルとしてアップロードしてください。JSON 形式のリクエストボディや画像 URL は使用しません。認識設定はエンドポイントが自動で選択します。

## リクエスト例

サーバー側で `IMG2EXCEL_API_KEY` を設定して実行してください。Python では `pip install requests` が必要です。Node.js は 20 以降を使用してください。


### cURL

```bash
curl --fail-with-body --max-time 330 -i https://img2excel.net/api/v1/handwriting-to-excel \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY" \
  -H "Idempotency-Key: handwriting-to-excel-001" \
  -F "file=@handwritten-log.jpg"
```


### Python

```python
import os
import requests

with open("handwritten-log.jpg", "rb") as image:
    response = requests.post(
        "https://img2excel.net/api/v1/handwriting-to-excel",
        headers={
            "Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}",
            "Idempotency-Key": "handwritten-log-001",
        },
        files={"file": ("handwritten-log.jpg", image, "image/jpeg")},
        timeout=330,
    )

response.raise_for_status()
job = response.json()
print(job["result"]["download_url"])
```


### Node.js

```ts
import { readFile } from 'node:fs/promises';

const file = await readFile('handwritten-log.jpg');
const form = new FormData();
form.set('file', new File([file], 'handwritten-log.jpg', { type: 'image/jpeg' }));

const response = await fetch('https://img2excel.net/api/v1/handwriting-to-excel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.IMG2EXCEL_API_KEY}`,
    'Idempotency-Key': 'handwritten-log-001',
  },
  body: form,
  signal: AbortSignal.timeout(330_000),
});

if (!response.ok) throw new Error(await response.text());
const job = await response.json();
console.log(job.result.download_url);
```




## レスポンス

**200 OK** — 変換が完了しました。`result.download_url` から Excel ファイルをダウンロードしてください。以下の URL は説明用の例です。

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "handwriting-to-excel",
  "status": "succeeded",
  "credits_reserved": 2,
  "credits_used": 2,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:08.000Z",
  "result": {
    "filename": "table_result.xlsx",
    "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "size_bytes": 17330,
    "download_url": "https://signed-storage-url.example/...",
    "download_url_expires_in": 900
  }
}
```

**422 Unprocessable Entity** — 変換に失敗しました。レスポンスにはジョブ ID、`status: "failed"`、`error.code`、`error.message` が含まれます。変換に失敗した場合、クレジットは消費されません。

冪等キーに対応するジョブがすでに存在する場合、`Idempotent-Replayed: true` が返されます。完了済みのジョブは `200`、結果の保持期間が終了したジョブは `410` を返します。元のジョブが待機中または実行中の場合は、`202` と `Location` レスポンスヘッダーが返されます。新しい変換を作成せず、この URL で状態を確認してください。

レスポンスの各フィールドは [ジョブとエラー](https://img2excel.net/ja/docs/api/jobs) を参照してください。同じ変換タイプの同期・非同期リクエストは、ジョブ記録、アカウントの制限、冪等キーを共有します。

同期エンドポイントは変換が完了するまで待機します。HTTP クライアントのタイムアウトを 330 秒に設定してください。接続がタイムアウトした場合は、同じ `Idempotency-Key` で再試行してください。新しいキーを使用するのは、新たな変換を開始する場合だけです。

## 非同期変換（任意）

完了を待たずに送信する場合は、`POST /api/v1/handwriting-to-excel/jobs` を使用してください。アップロードするフィールドと認証方法は同じです。新しいジョブには `202`、ジョブ ID、`Location` レスポンスヘッダーが返されます。`GET /api/v1/jobs/{job_id}` を 2〜3 秒ごとに確認し、`succeeded`、`failed`、`expired` のいずれかになったらポーリングを停止してください。成功した場合は `result.download_url` からダウンロードします。ポーリングの実装例は [ジョブとエラー](https://img2excel.net/ja/docs/api/jobs) を参照してください。

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
API ドキュメント全文: https://img2excel.net/ja/docs/api/text/llms-full.txt