# 快速開始

完成第一次 API 調用並下載 Excel 文件。

文檔原文: https://img2excel.net/zh-HK/docs/api/getting-started

IMG2Excel API 可將表格圖片轉換為可編輯的 Excel 工作簿。建議優先使用同步接口：上傳圖片，等待轉換完成，再從響應中的下載地址取得 XLSX 文件。異步接口也會繼續提供。

| 參數 | 值 |
| --- | --- |
| 基礎 URL | `https://img2excel.net` |
| 認證方式 | `Authorization: Bearer $IMG2EXCEL_API_KEY` |
| API 使用權限 | 購買 Business 或 專業版 點數套裝 |
| 輸入 | 一張 PNG、JPG 或 JPEG 圖片，最大 4MB |
| 輸出 | 可編輯的 `.xlsx` 文件 |

## 1. 設定 API 密鑰

從 [API 設定](https://img2excel.net/zh-HK/settings/api) 複製密鑰，並儲存在服務端的環境變量中：

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

請妥善保管密鑰，不要放在瀏覽器代碼或公開的代碼倉庫中。

## 2. 上傳表格圖片

根據圖片內容選擇對應的接口：

| 圖片類型 | 接口 |
| --- | --- |
| 印刷表格、屏幕截圖或掃描電子表格 | [圖片轉 Excel](https://img2excel.net/zh-HK/docs/api/image-to-excel) |
| 手寫表格、日誌或紀錄 | [手寫轉 Excel](https://img2excel.net/zh-HK/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 僅為示意，請使用實際響應中的下載地址。

```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` 響應頭。每隔 2–3 秒查詢該地址，直到狀態為 `succeeded`、`failed` 或 `expired`。輪詢代碼請參閱 [任務與錯誤](https://img2excel.net/zh-HK/docs/api/jobs)。

同步轉換失敗時返回 `422`，並提供 `error.code` 和 `error.message`。使用同一冪等鍵重試會返回原任務；若任務仍在執行中，返回 `202`，可繼續查詢 `Location` 地址。結果已過期則返回 `410`。

## 使用 AI 編程助手

點擊上方的 **複製給 AI**，將指示貼到 ChatGPT、Claude、Gemini、Cursor 或其他助手。告訴它你使用的服務端語言，以及需要轉換印刷表格還是手寫內容。各接口頁面也提供獨立的複製功能及 Python / Node.js 範例。

完整的 API 定義請參閱 [OpenAPI 規格](https://img2excel.net/api/openapi.json) 或 [完整 API 文檔](https://img2excel.net/zh-HK/docs/api/text/llms-full.txt)。

---

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