Image to Table

POST /api/v1/image-to-table

Send a single image as multipart image to POST /api/v1/image-to-table; supported format values are json (default), csv and xlsx. Replace YOUR_API_KEY and table.png. Use a server-side request and the shared Bearer authentication instructions.

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'

A successful JSON response contains request_id, usage, billing, and a tables array of {title, html}. The HTML is sanitized table markup; a generated Table N label means no caption was detected. The model's raw recognition text is not returned in this public JSON response. Example values are illustrative:

{
  "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>"
    }
  ]
}

For the same picture and same Idempotency-Key, you can request other output formats without rerunning recognition or charging again:

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: one table is a normal UTF-8 CSV. With multiple tables, the response contains sections separated by a blank line. Each section starts with # Table N: Title followed by its table's CSV. This multi-section response is not a standard single-table CSV; split it into separate CSV files before importing. Formula-like cells are escaped to prevent spreadsheet formula injection
• XLSX: a real Excel workbook, with a separate Table N worksheet for each detected table. Merged cells retain row and column spans. All cell values, including numbers and leading zeroes, are stored as text; convert reviewed values to numbers in Excel if needed
• Images and limits: Table API accepts only PNG, JPEG and WebP, up to 10 MB and the shared request limits. The website also accepts formats such as HEIC, HEIF and BMP; these are not available to the API. No PDF, multi-page input, batch upload or multiple images per request. One image may contain several tables

Table-specific failures and shared rules

An empty or invalid table result returns 422 no_tables before settlement and is not charged. If CSV/XLSX export fails after successful recognition and settlement, the API returns 503 export_failed with recognition_succeeded: true. Retry with the same image, account and Idempotency-Key using format=json within the replay window; do not create a new operation for an uncertain charge. Error responses are JSON with request_id, error.code and Cache-Control: no-store; successful downloads include X-Request-Id, X-OCR-Charged-USD and X-OCR-Price-Version.

Changing format keeps the original recognition and charge. A completed result is replayable for 24 hours; replays still count toward rate limits. Reusing a key across endpoints returns 409 idempotency_conflict; API balance is separate from website credits. Consult pricing and reservation, image and request limits, and idempotency / safe retries for the rules shared by both endpoints.