# 手寫轉 Excel

使用針對手寫內容優化的識別方式，將手寫表格、日誌或紀錄轉換為可編輯的 XLSX 工作簿。

文檔原文: https://img2excel.net/zh-HK/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 圖片，最大 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` 響應頭。請查詢該地址，不要重複建立轉換任務。

完整響應字段請參閱 [任務與錯誤](https://img2excel.net/zh-HK/docs/api/jobs)。同一轉換類型的同步與異步調用共用任務記錄、帳戶限制和冪等鍵。

同步接口會等待轉換完成。請將 HTTP 客戶端超時設為 330 秒。若連接超時，使用原 `Idempotency-Key` 重試；只有需要建立新的轉換任務時才使用新值。

## 異步轉換（可選）

若不想等待轉換完成，可使用 `POST /api/v1/handwriting-to-excel/jobs`，上傳字段及認證方式相同。新任務返回 `202`、任務 ID 和 `Location` 響應頭。每隔 2–3 秒查詢 `GET /api/v1/jobs/{job_id}`，直到狀態為 `succeeded`、`failed` 或 `expired`。成功後從 `result.download_url` 下載文件。輪詢代碼請參閱 [任務與錯誤](https://img2excel.net/zh-HK/docs/api/jobs)。

---

OpenAPI 3.1: https://img2excel.net/api/openapi.json
完整 API 文檔: https://img2excel.net/zh-HK/docs/api/text/llms-full.txt