# クイックスタート

IMG2Excel API の認証、画像のアップロード、同期変換の実行、Excel ファイルのダウンロードを順に解説します。

公式ドキュメント: https://img2excel.net/ja/docs/api/getting-started

IMG2Excel API は、表の画像を編集可能な Excel ブックに変換します。同期エンドポイントの利用を推奨します。画像を送信すると、変換完了後にダウンロード URL が返され、その URL から XLSX ファイルを取得できます。非同期エンドポイントも引き続き利用できます。

| 項目 | 値 |
| --- | --- |
| ベース URL | `https://img2excel.net` |
| 認証 | `Authorization: Bearer $IMG2EXCEL_API_KEY` |
| API の利用条件 | Business または プロフェッショナル クレジットパッケージの購入 |
| 入力 | PNG、JPG、JPEG 画像 1 枚、最大 4MB |
| 出力 | 編集可能な `.xlsx` ファイル |

## 1. API キーを設定する

[API 設定](https://img2excel.net/ja/settings/api) からキーをコピーし、サーバー側の環境変数に保存します。

```bash
export IMG2EXCEL_API_KEY="your_api_key"
```

API キーは厳重に管理し、ブラウザーで実行するコードや公開リポジトリに含めないでください。

## 2. 表の画像をアップロードする

画像の内容に応じてエンドポイントを選びます。

| 画像 | エンドポイント |
| --- | --- |
| 印刷された表、スクリーンショット、スキャンした表計算シート | [画像から Excel](https://img2excel.net/ja/docs/api/image-to-excel) |
| 手書きの表、日誌、記録 | [手書きから Excel](https://img2excel.net/ja/docs/api/handwriting-to-excel) |

以下の例では印刷された表を送信します。`table.png` を画像のパスに置き換えてください。手書きの場合は `/api/v1/handwriting-to-excel` を使用します。

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

新しい画像ごとに異なる `Idempotency-Key` を使用します。同じアップロードを再試行する場合に限り、同じ値を再利用してください。

同期リクエストは変換完了後に **200 OK** を返します。レスポンスには `result.download_url` が含まれます。以下の URL は説明用の例です。実際のレスポンスに含まれる URL を使用してください。

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "succeeded",
  "credits_reserved": 1,
  "credits_used": 1,
  "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
  }
}
```

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

## 3. Excel ファイルをダウンロードする

成功したレスポンスから `result.download_url` をコピーします。

```bash
curl --fail --location "PASTE_RESULT_DOWNLOAD_URL_HERE" --output table.xlsx
```

ダウンロード URL の有効期間は 15 分です。結果は完了後 24 時間保持されます。その期間中にジョブを再取得すると、新しい URL を取得できます。変換が失敗した場合、クレジットは消費されません。

## 非同期変換（任意）

バックグラウンドで処理する場合は、変換エンドポイントの末尾に `/jobs` を追加してください。新しいジョブには `202`、ジョブ ID、`Location` レスポンスヘッダーが返されます。その URL を 2〜3 秒ごとに確認し、`succeeded`、`failed`、`expired` のいずれかになったら停止してください。ポーリングの実装例は [ジョブとエラー](https://img2excel.net/ja/docs/api/jobs) を参照してください。

同期変換に失敗した場合は、`422` と `error.code`、`error.message` が返されます。同じ冪等キーで再試行すると元のジョブが返されます。実行中の場合は `202` が返されるため、`Location` の URL で状態を確認してください。結果の保持期間が終了している場合は `410` が返されます。

## AI コーディングアシスタントを使う

上部の **AI にコピー** を選び、ChatGPT、Claude、Gemini、Cursor などに指示を貼り付けます。使用するサーバー側のプログラミング言語と、変換対象が印刷された表か手書きの表かを伝えてください。各エンドポイントのページにもコピー機能と Python / Node.js の例があります。

API の詳細な定義は [OpenAPI 仕様](https://img2excel.net/api/openapi.json) または [API ドキュメント全文](https://img2excel.net/ja/docs/api/text/llms-full.txt) を参照してください。

---

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