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

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.

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