开发者文档

从一张图片，连接您的工作流程

通过 REST API 提交图片、查询转换进度，并下载结构化结果。

快速开始

以 multipart 表单上传 JPG、PNG、BMP 或 TIFF 图片。接口返回 202 和任务 ID。tableOnly=true 仅提取表格；false 同时提取周围文字。

cURL · POST /api/v1/jobs

curl -X POST 'https://jpg2excel.app/api/v1/jobs' \
  -H "Authorization: Bearer $JPG2EXCEL_API_KEY" \
  -H 'Idempotency-Key: invoice-2026-10-001' \
  -F 'file=@table.jpg' \
  -F 'tableOnly=true'

HTTP 202 · application/json

{
  "code": 0,
  "msg": "OK",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "queued",
    "filename": "table.jpg",
    "createdAt": "2026-10-08T08:00:00.000Z",
    "completedAt": null,
    "resultExpiresAt": null,
    "creditsUsed": 0,
    "error": null,
    "resultFormats": [],
    "statusUrl": "/api/v1/jobs/550e8400-e29b-41d4-a716-446655440000",
    "resultUrl": null
  }
}

以下 Python 示例提交图片、等待完成并保存 Excel 文件。请先在服务器环境中设置 JPG2EXCEL_API_KEY。

Python · pip install requests

import os
import time
import uuid
import requests

base = "https://jpg2excel.app"
headers = {"Authorization": f"Bearer {os.environ['JPG2EXCEL_API_KEY']}"}
# Keep this value if you retry the same submission.
submission_key = str(uuid.uuid4())

with open("table.jpg", "rb") as image:
    response = requests.post(
        f"{base}/api/v1/jobs",
        headers={**headers, "Idempotency-Key": submission_key},
        files={"file": ("table.jpg", image, "image/jpeg")},
        data={"tableOnly": "true"},
        timeout=60,
    )
response.raise_for_status()
job = response.json()["data"]
deadline = time.monotonic() + 600

while job["status"] in ("queued", "processing"):
    if time.monotonic() > deadline:
        raise TimeoutError("Conversion is still running; query its job ID later.")
    time.sleep(2)
    response = requests.get(base + job["statusUrl"], headers=headers, timeout=30)
    if response.status_code == 429:
        time.sleep(int(response.headers.get("Retry-After", "5")))
        continue
    response.raise_for_status()
    job = response.json()["data"]

if job["status"] != "succeeded":
    raise RuntimeError(job.get("error") or job["status"])

result = requests.get(
    base + job["resultUrl"], headers=headers,
    params={"format": "xlsx"}, timeout=60,
)
result.raise_for_status()
with open("result.xlsx", "wb") as output:
    output.write(result.content)

身份验证

在 Authorization 请求头中使用 Plus 或 Enterprise API 密钥。团队密钥消耗团队积分。请在服务器保存密钥，勿在浏览器代码中暴露。

HTTP header

Authorization: Bearer j2e_live_YOUR_SECRET_KEY

jobs:write 用于提交任务；jobs:read 用于查询任务、下载结果与查询额度。请仅为密钥授予集成所需的权限。

方法	接口	用途
POST	/api/v1/jobs	提交图片
GET	/api/v1/jobs/{id}	查询任务状态
GET	/api/v1/jobs/{id}/result	下载结构化结果
GET	/api/v1/usage	查询可用积分和限制

转换任务

轮询状态地址，直到任务成功或失败。建议从 2 秒间隔开始，遇到频率限制时延长间隔。

queuedprocessingsucceeded/failed

cURL · GET job status

curl 'https://jpg2excel.app/api/v1/jobs/JOB_ID' \
  -H "Authorization: Bearer $JPG2EXCEL_API_KEY"

为每次业务提交设置 Idempotency-Key。重试同一文件与参数时复用该值，以免重复创建任务或扣费。

重复提交相同业务键时返回原任务和 HTTP 200。相同键用于不同文件或参数时返回 HTTP 409。业务键在工作空间范围内生效。

下载结果

任务成功后可下载 XLSX、CSV 或 JSON。结果有效期以任务响应中的 resultExpiresAt 为准。

cURL · GET XLSX result

curl 'https://jpg2excel.app/api/v1/jobs/JOB_ID/result?format=xlsx' \
  -H "Authorization: Bearer $JPG2EXCEL_API_KEY" \
  --output result.xlsx

xlsx

可编辑 Excel 工作簿

csv

第一个表格导出为 CSV

json

JSON 响应中的结构化表格

结果在完成后保留 24 小时，请及时保存至您自己的存储。TIFF 必须为单页，此接口不支持 PDF。

积分与限制

网页与 API 共用积分。成功任务扣除积分，失败任务释放预留额度。套餐决定文件大小、并发和请求频率上限。API 任务始终需要积分。

cURL · GET workspace usage

curl 'https://jpg2excel.app/api/v1/usage' \
  -H "Authorization: Bearer $JPG2EXCEL_API_KEY"

密钥限额按 UTC 自然月重置，成员限额跟随团队每月积分更新周期，并计算已完成和预留的积分。限额不会增加积分，成员限额为零时无法提交新转换。

Enterprise 包含 3 个席位（含所有者）。额外席位每人 $5/月或 $50/年。团队共享积分与并发额度，仅所有者和管理员可管理团队密钥。

错误与重试

错误采用统一 JSON 结构：code、msg、data。请结合 HTTP 状态码和错误代码决定是否重试。

HTTP 429 · Retry-After: 60

{
  "code": 1006,
  "msg": "Workspace request rate limit reached.",
  "data": null
}

HTTP	code	处理方式
400	1001 / 2004 / 2005	检查请求字段、文件和参数后重试。
401	1002	检查密钥。已过期或已撤销的密钥无法验证。
402	3002 / 3003	补充积分，或等待密钥、成员的月限额重置。
403	1003	检查密钥权限与工作空间订阅状态。
404 / 410	1004 / 2007	检查任务 ID 和工作空间；已过期结果无法下载。
409	1005	结果尚未就绪，或业务键已用于不同输入。
413 / 415	2002 / 2003	缩小文件或使用受支持的图片格式。
429	1006	等待 Retry-After 指定的时间后重试，并降低频率或并发数。
503	1007	延长间隔后重试，并保持相同的业务键。

转换失败会记录在任务的 error 字段中，即使查询请求本身返回 HTTP 200。代码 2006、2008、2009 分别表示转换失败、超时和未识别到表格。