图片转表格 | FreeAIOCR

POST /api/v1/image-to-table

使用 multipart image 字段向 POST /api/v1/image-to-table 上传一张图片，format 仅支持 json（默认）、csv、xlsx。替换 YOUR_API_KEY 与 table.png，并在服务端调用；密钥使用方式见Bearer 认证。

curl --silent --show-error --include --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-table?format=json' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-table-request-0001' \
  -F 'image=@table.png'

JSON 成功响应包含 request_id、usage、billing 和 tables 数组，每项为 {title, html}。HTML 是清理过的安全表格标记；Table N 是没有识别到标题时的显示名称，不是原图标题。对外 JSON 不包含原始模型文本。以下是示例：

{
  "request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
  "usage": {
    "input_tokens": 2000,
    "output_tokens": 4000
  },
  "billing": {
    "currency": "USD",
    "price_version": "2026-10-26-v1",
    "base_usd": "0.002000000",
    "input_overage_usd": "0.000000000",
    "output_overage_usd": "0.002400000",
    "total_usd": "0.004400000"
  },
  "tables": [
    {
      "title": "Sales",
      "html": "<table><tbody><tr><th>Item</th><th>Qty</th></tr><tr><td>Notebook</td><td>0012</td></tr></tbody></table>"
    }
  ]
}

对同一张图片使用相同的 Idempotency-Key，可以切换格式而不重复识别、扣费：

curl --silent --show-error --fail --output tables.csv --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-table?format=csv' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-table-request-0001' \
  -F 'image=@table.png'

curl --silent --show-error --fail --output tables.xlsx --max-time 150 \
  'https://freeaiocr.com/api/v1/image-to-table?format=xlsx' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: example-table-request-0001' \
  -F 'image=@table.png'

CSV：单表返回正常的 UTF-8 CSV；多表返回空行分隔的多个段落，每段以 # Table N: Title 开头，后面接该表的 CSV。它不是单张标准 CSV，导入 Excel 或其他程序前应拆成独立 CSV。疑似公式的内容会做防注入处理
XLSX：真正的 Excel 文件，每个检测到的表格位于单独的 Table N 工作表，保留跨行、跨列合并单元格。所有单元格包括数字和前导零都按文本保存，需要计算时请先校对再转换数字
图片限制：API 仅支持 PNG、JPEG、WebP，单图不超过 10 MB，像素、token 及处理限制见请求限制。网页工具还可接受 HEIC、HEIF、BMP 等格式，但API 不支持。不支持 PDF、多页文件、批量上传或一次提交多张图片；单张图片内可以检测多个表格

表格专属错误与通用规则

未识别到有效表格返回 422 no_tables，在结算前释放冻结金额且不收费。识别与结算成功后若 CSV/XLSX 导出失败，返回 503 export_failed 及 recognition_succeeded: true；在回放期内使用原图片、账户和 Idempotency-Key 改为 format=json 重试，不要因计费不确定而新建操作。错误始终是含 request_id、error.code 的 JSON，带 Cache-Control: no-store；成功文件响应带 X-Request-Id、X-OCR-Charged-USD、X-OCR-Price-Version。

同一操作切换 format 不重复识别或扣费，结果可在 24 小时内重放，重放仍计入频率限制。跨文字与表格接口复用编号会返回 409 idempotency_conflict；API 余额与网页积分独立。请查阅价格与冻结规则、请求限制及幂等与安全重试。