Mathpix: image OCR is sync, document conversion is async with polling

Mathpix: image OCR is sync, document conversion is async with polling

TL;DR

Route images to the v3/text image endpoint and PDFs to the async document flow, then poll status until the conversion completes before fetching output. If your Mathpix call fails on a PDF, check which endpoint you hit first. For batch pipelines, use the confidence thresholds to catch bad OCR instead of trusting every result.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Context: Repo README (mathpix/mpxpy, the official Python client): documents that single-image OCR and document conversion are two different flows. Images go to v3/text synchronously, but PDF and document conversion is async: submit the file, then poll for completion before downloading outputs in MMD, Markdown, DOCX, LaTeX, or HTML. Gotcha that trips agents: POSTing a PDF to the image endpoint fails. The README also documents an isasync flag for non-interactive image requests and confidencethreshold knobs that raise errors on low-confidence OCR instead of silently returning junk.

Source: Repo README (mathpix/mpxpy, the official Python client): documents that single-image OCR and document conversion are two different flows. Images go to v3/text synchronously, but PDF and document conversion is async: submit the file, then poll for completion before downloading outputs in MMD, Markdown, DOCX, LaTeX, or HTML. Gotcha that trips agents: POSTing a PDF to the image endpoint fails. The README also documents an isasync flag for non-interactive image requests and confidencethreshold knobs that raise errors on low-confidence OCR instead of silently returning junk.

Verified resolution: Route images to the v3/text image endpoint and PDFs to the async document flow, then poll status until the conversion completes before fetching output. If your Mathpix call fails on a PDF, check which endpoint you hit first. For batch pipelines, use the confidence thresholds to catch bad OCR instead of trusting every result.

Source URL: https://github.com/mathpix/mpxpy/blob/HEAD/README.md