# 任務與錯誤

查詢任務、下載工作簿，並排查請求失敗的原因。

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

`GET /api/v1/jobs/{job_id}`

同步接口直接返回轉換結果。異步處理、冪等重試返回待處理任務，或需要在結果保留期內刷新下載地址時，可使用此任務查詢接口。同步轉換失敗會返回 `422` 及任務響應；查詢已存在的任務仍返回 `200`，因此應檢查 `status`。

查詢轉換任務的目前狀態。圖片轉 Excel 和手寫轉 Excel 共用此接口。

## 請求

| 參數 | 位置 | 必填 | 說明 |
| --- | --- | --- | --- |
| `job_id` | 路徑 | 是 | 建立任務時返回的 `id`。 |
| `Authorization` | 請求頭 | 是 | `Bearer $IMG2EXCEL_API_KEY`。密鑰必須屬於建立任務的帳戶。 |

```bash
curl --fail-with-body https://img2excel.net/api/v1/jobs/job_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $IMG2EXCEL_API_KEY"
```

有效請求會返回 **200 OK**，即使轉換任務已失敗，也會返回此 HTTP 狀態碼。請務必檢查 JSON 中的 `status`；HTTP 請求成功並不代表工作簿已完成。

## 任務狀態

| 狀態 | 意義 | 下一步 |
| --- | --- | --- |
| `queued` | 已接受上傳，正在等候執行。 | 2–3 秒後再次查詢。 |
| `processing` | 正在轉換。 | 2–3 秒後再次查詢。 |
| `succeeded` | 工作簿已完成。 | 下載 `result.download_url` 並停止輪詢。 |
| `failed` | 無法完成轉換。 | 閱讀 `error.code` 和 `error.message`，並停止輪詢。 |
| `expired` | 結果保留期限已結束。 | 停止輪詢。如有需要，使用新的冪等鍵提交新任務。 |

## 響應

### 轉換成功

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "succeeded",
  "credits_reserved": 1,
  "credits_used": 1,
  "created_at": "2026-09-07T12:00:00.000Z",
  "completed_at": "2026-09-07T12:00:18.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
  }
}

```

以上下載 URL 僅為示意，請使用你自己的任務所返回的 URL。

| 字段 | 類型 | 說明 |
| --- | --- | --- |
| `id` | 字符串 | 任務識別碼。 |
| `type` | 字符串 | `image-to-excel` 或 `handwriting-to-excel`。 |
| `status` | 字符串 | 上述五種狀態之一。 |
| `credits_reserved` | 整數 | 轉換所需點數。 |
| `credits_used` | 整數 | 轉換已消耗的點數。 |
| `created_at` | 字符串 | ISO 8601 格式的 UTC 時間。 |
| `completed_at` | 字符串或 null | 完成時間；尚未完成時為 `null`。 |
| `result` | 對象 | 任務成功且結果可用時提供。 |
| `error` | 對象 | 轉換失敗時提供，包含 `code` 和 `message`。 |

### 結果字段

| 字段 | 類型 | 說明 |
| --- | --- | --- |
| `filename` | 字符串 | 建議使用的工作簿檔名。 |
| `content_type` | 字符串 | XLSX MIME 類型。 |
| `size_bytes` | 整數或 null | 文件大小（字節）；無法取得時為 `null`。 |
| `download_url` | 字符串 | 帶簽名的臨時下載 URL。 |
| `download_url_expires_in` | 整數 | URL 有效秒數：`900`（15 分鐘）。 |

結果在完成後保留 24 小時。若下載 URL 在此期間過期，重新查詢任務即可取得新的 URL。請勿記錄或公開分享帶簽名的下載 URL。

### 轉換失敗

轉換失敗會在任務響應中回報，例如：

```json
{
  "id": "job_0123456789abcdef0123456789abcdef",
  "type": "image-to-excel",
  "status": "failed",
  "credits_reserved": 1,
  "credits_used": 0,
  "created_at": "2026-10-04T09:00:00.000Z",
  "completed_at": "2026-10-04T09:00:18.000Z",
  "error": {
    "code": "CONVERSION_FAILED",
    "message": "The conversion could not be completed."
  }
}
```

轉換失敗不會消耗點數。重試前請先查看返回訊息：新的轉換需要新的冪等鍵。重複使用原鍵值只會取得同一個失敗任務。

## 輪詢並下載

執行 `pip install requests` 安裝 `requests`，設定 `IMG2EXCEL_API_KEY`，並將 `job_id` 換成你的任務 ID。此範例最多發出 60 次狀態查詢。遇到網絡或 HTTP 錯誤時，程序會停止；正式整合應依照下方重試指引處理暫時性失敗。

```python
import os
import time
import requests

job_id = "job_0123456789abcdef0123456789abcdef"
headers = {"Authorization": f"Bearer {os.environ['IMG2EXCEL_API_KEY']}"}

for _ in range(60):
    response = requests.get(
        f"https://img2excel.net/api/v1/jobs/{job_id}",
        headers=headers,
        timeout=30,
    )
    response.raise_for_status()
    job = response.json()

    if job["status"] == "succeeded":
        xlsx = requests.get(job["result"]["download_url"], timeout=60)
        xlsx.raise_for_status()
        with open(job["result"]["filename"], "wb") as output:
            output.write(xlsx.content)
        break
    if job["status"] in ("failed", "expired"):
        raise RuntimeError(job.get("error", {"code": job["status"]}))

    time.sleep(2)
else:
    raise TimeoutError("IMG2Excel conversion did not finish in time")

```

## 請求錯誤

HTTP 請求被拒絕時，會返回非 2xx 狀態碼及錯誤對象：

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "A valid API key is required."
  }
}
```

| HTTP 狀態碼 | 錯誤碼 | 原因 | 處理方式 |
| --- | --- | --- | --- |
| 400 | `INVALID_REQUEST` | 無法將請求體解析為 multipart 表單資料。 | 使用 HTTP 客戶端的 multipart 文件上傳功能。 |
| 400 | `INVALID_FILE` | 缺少 `file` 字段，或該值不是文件。 | 使用 `file` 字段附上圖片。 |
| 400 | `INVALID_IDEMPOTENCY_KEY` | 重試鍵值超過 200 個字符。 | 縮短請求頭值。 |
| 401 | `INVALID_API_KEY` | 密鑰缺失、無效、過期、已撤銷，或缺少對應轉換權限。 | 檢查 Bearer 請求頭及 [API 設定](https://img2excel.net/zh-HK/settings/api) 中的密鑰。 |
| 403 | `API_ACCESS_REQUIRED` | 帳戶沒有 API 使用權限。 | 購買 Business 或 專業版 點數套裝。 |
| 404 | `JOB_NOT_FOUND` | 任務不存在，或屬於其他帳戶。 | 核對 ID，並使用建立任務的帳戶所屬密鑰。 |
| 409 | `JOB_CONFLICT` | 因衝突而無法建立轉換任務。 | 使用原冪等鍵重試，以取得現有任務。 |
| 413 | `FILE_TOO_LARGE` | 文件超過 4MB。 | 縮小圖片後再上傳。 |
| 429 | `RATE_LIMITED` | 過去一分鐘建立的任務過多。 | 等候 `Retry-After` 指定時間，再使用相同冪等鍵重試。 |
| 429 | `CONCURRENCY_LIMITED` | 帳戶中排隊或執行中的任務過多。 | 等候現有任務完成後再提交。 |

點數不足或識別失敗可能在任務被接受**之後**才發生。查詢任務時，會以 `status: "failed"` 搭配 `error.code` 和 `error.message` 回報，而不一定在上傳時拒絕請求。若訊息顯示點數不足，請檢查帳戶餘額。

## 限制與重試

| 限制 | 值 |
| --- | --- |
| 每個帳戶的新任務數 | 每分鐘 30 個，兩個轉換接口共用 |
| 同時排隊或執行中的任務數 | Business：3 個；專業版：10 個 |
| 文件大小 | 最大 4MB |
| 下載 URL 有效期 | 15 分鐘 |
| 結果保留期限 | 成功完成後 24 小時 |

遇到 `429` 響應時，若有 `Retry-After` 響應頭，請遵守其等候時間。暫時性的 `5xx` 響應或網絡失敗，請採用指數退避重試：逐次延長等待時間，並加入隨機延遲。重試上傳時重複使用原冪等鍵；重試狀態查詢時使用同一個任務 ID。請在應用程序中設定整體輪詢期限。

不要自動重試無效請求或認證錯誤，應先修正請求。若問題持續，請向 [支援團隊](mailto:support@img2excel.net) 提供任務 ID 和錯誤碼，切勿附上 API 密鑰或下載 URL。

---

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