Process Images

Process a single image containing math, text, tables, or chemistry diagrams.

See the image processing guide for step-by-step examples.

POST v3/text

POST api.mathpix.com/v3/text

Accepts an image URL, base64-encoded image, or file upload (multipart form-data with options_json). Returns structured content as Mathpix Markdown (with LaTeX math inside \( ... \) and \[ ... \] delimiters), HTML, or extracted data formats. Chemistry diagrams are returned as <smiles>...</smiles> SMILES notation.

info

• EXIF data is ignored for all images, including EXIF orientation
• When sending an image via multipart form-data, pass all options as stringified JSON in a top-level options_json parameter
• Request limits: 5 MB JSON body, 10 MB image download from URL, 2 MB base64-encoded image, 15 second URL download timeout - see Limits & Quotas
• Figures embedded in the input image are not extracted as separate image crops. /v3/text treats the input as a single image and returns its bounding-box geometry (via cnt in line_data) but does not crop sub-regions or upload them to our CDN. If you need per-figure cropped images (with CDN URLs), use /v3/pdf instead, even for single-image workloads - it returns one cropped image per detected figure.

Example

cURL

curl -X POST https://api.mathpix.com/v3/text \
-H 'app_id: APP_ID' \
-H 'app_key: APP_KEY' \
-H 'Content-Type: application/json' \
--data '{"src": "https://mathpix-ocr-examples.s3.amazonaws.com/cases_hw.jpg", "math_inline_delimiters": ["$", "$"], "rm_spaces": true}'

Python

import requests, json
r = requests.post("https://api.mathpix.com/v3/text",
    json={
        "src": "https://mathpix-ocr-examples.s3.amazonaws.com/cases_hw.jpg",
        "math_inline_delimiters": ["$", "$"],
        "rm_spaces": True
    },
    headers={
        "app_id": "APP_ID",
        "app_key": "APP_KEY",
        "Content-type": "application/json"
    }
)
print(json.dumps(r.json(), indent=4, sort_keys=True))

JavaScript / TypeScript

const response = await fetch("https://api.mathpix.com/v3/text", {
  method: "POST",
  headers: {
    app_id: "APP_ID",
    app_key: "APP_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    src: "https://mathpix-ocr-examples.s3.amazonaws.com/cases_hw.jpg",
    math_inline_delimiters: ["$", "$"],
    rm_spaces: true,
  }),
});
const result = await response.json();
console.log(JSON.stringify(result, null, 2));

Go

body := bytes.NewBufferString(`{
    "src": "https://mathpix-ocr-examples.s3.amazonaws.com/cases_hw.jpg",
    "math_inline_delimiters": ["$", "$"],
    "rm_spaces": true
}`)
req, _ := http.NewRequest("POST", "https://api.mathpix.com/v3/text", body)
req.Header.Set("app_id", "APP_ID")
req.Header.Set("app_key", "APP_KEY")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
result, _ := io.ReadAll(resp.Body)
fmt.Println(string(result))

Java

HttpClient client = HttpClient.newHttpClient();
String body = """
    {
      "src": "https://mathpix-ocr-examples.s3.amazonaws.com/cases_hw.jpg",
      "math_inline_delimiters": ["$", "$"],
      "rm_spaces": true
    }
    """;
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.mathpix.com/v3/text"))
    .header("app_id", "APP_ID")
    .header("app_key", "APP_KEY")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Example response

{
  "request_id": "14b53567-9f6c-4895-ab3d-e4a8ae18f9c1",
  "text": "$f(x)=\\left\\{\\begin{array}{ll}x^{2} & \\text { if } x<0 \\\\ 2 x & \\text { if } x \\geq 0\\end{array}\\right.$",
  "confidence": 1,
  "confidence_rate": 1,
  "is_printed": false,
  "is_handwritten": true,
  "image_height": 332,
  "image_width": 850,
  "version": "SuperNet-200"
}

Request parameters

src string (optional)

Image URL or base64-encoded image (e.g. data:image/jpeg;base64,...)

metadata object (optional)

Key-value object. Supports improve_mathpix for extra privacy controls.

tags string[] (optional)

Tags are lists of strings that can be used to identify results. see query image results

async bool[] (optional)

This flag is to be used when sending non-interactive requests

callback Callback (optional)

Webhook for asynchronous result delivery

formats string[] (optional)

List of formats, see Format Descriptions. Empty array or object returns the text format.

Values

text, data, html, latex_styled

data_options DataOptions (optional)

Specifies outputs for data and html return fields

include_detected_alphabets bool (optional)

Return detected alphabets

alphabets_allowed AlphabetsAllowed (optional)

Specify which alphabets you don't want in the output

region Region (optional)

Specify the image area with pixel coordinates. All four properties are required if region is provided. Empty object {} is valid (treated as no region)

enable_blue_hsv_filter bool (optional), default value is false

Enables a special mode of image processing where it OCRs only blue hue text.

confidence_threshold number in [0,1] (optional)

Specifies threshold for triggering math_confidence errors. Returns error when confidence is below this value

confidence_rate_threshold number in [0,1] (optional), default value is 0.75

Specifies threshold for triggering math_confidence errors at the symbol level.

include_equation_tags bool (optional)

Specifies whether to include equation number tags inside equations LaTeX. When set to true, it sets "idiomatic_eqn_arrays": true, because equation numbering works better in those environments compared to the array environment.

Example

\tag{eq_number}, where eq_number is an equation number (e.g. 1.12)

See output option examples for a numbered equation returned with and without its tag.

include_line_data bool (optional)

Specifies whether to return information segmented line by line, see LineData object section for details.

Note: line_data includes line types such as diagram, chart, and figure_label with their bounding-box geometry (cnt), but the figures themselves are not extracted as separate image crops by /v3/text. To get per-figure cropped images with CDN URLs, use /v3/pdf.

include_word_data bool (optional)

Specifies whether to return information segmented word by word, see WordData object section for details. Combining include_word_data: true with enable_document_layout: true is not supported.

include_lines_json bool (optional)

Return the shared page-region document in the lines_json response field. Defaults to the value of enable_document_layout: document-layout requests include it unless explicitly disabled, while ordinary image requests must opt in. This is independent of include_line_data and does not change the parser mode.

enable_document_layout bool (optional), default value is false

Enables full-page document layout recognition for images. Set to true to produce structured outputs such as nested itemize lists and lstlisting pseudocode and improve multi-line page parsing. The default retains snippet-oriented layout behavior. Document-layout mode also returns lines_json by default; use include_lines_json: false to suppress that field.

disable_lstlisting bool (optional), default value is false

Controls how recognized code and pseudocode are represented. By default, document-layout output uses \begin{lstlisting} so inline math can be rendered inside pseudocode. Set to true to emit standard Markdown triple-backtick fences instead; math inside the fallback fence remains plain text.

If you render MMD yourself, lstlisting requires mathpix-markdown-it 2.0.29 or newer, and version 3.0.0 is recommended. Older versions can omit the entire listing body when rendering. Mathpix-hosted conversion formats are rendered server-side and do not require a client upgrade.

See output option examples for the same image processed with this option off and on.

disable_itemize bool (optional), default value is false

Controls how recognized lists are represented. By default, lists are emitted as \begin{itemize} / \item environments. Set to true to emit each entry as a plain line with its marker kept inline (for example 1., -, □); lists inside tables are emitted as \\-separated rows instead of a nested itemize.

See output option examples for the same image processed with this option off and on.

include_smiles bool (optional), default value is false

Enable experimental chemistry diagram OCR, via RDKIT normalized SMILES with isomericSmiles=False, included in text output format, via MMD SMILES syntax <smiles>...</smiles>

See output option examples for a chemical diagram returned with and without its SMILES string.

include_inchi bool (optional)

Include InChI data as XML attributes inside <smiles> elements. Only applies when include_smiles is true.

Example

<smiles inchi="..." inchi_key="...">...</smiles>

See output option examples for the same diagram returned with and without InChI attributes.

include_page_info bool | string[] (optional), default value is true

Controls whether page info elements are included in the final text output. Page info refers to elements like headers, footers, page numbers, and detected QR codes that are not part of the main text. With enable_document_layout: true, detected QR codes are returned as cropped images by default; setting include_page_info: false excludes them.

Also accepts an array of page info type names to include only a subset: "margin_note" for margin notes (notes and comments beside the main text), "qr_code" for detected QR codes (returned as cropped images). For example, "include_page_info": ["margin_note"] keeps margin notes in the output while page numbers and headers stay excluded. Type names select what the model classifies each element as, not its physical position on the page - so "margin_note" returns everything recognized as margin-note content, wherever it appears.

The selectable names are exactly the page_info subtypes reported in line data. General page info without a subtype (headers, footers, page numbers, stamps, and similar) is only included via the boolean true.

See output option examples for a page processed with this option on and off.

auto_rotate_confidence_threshold number in [0,1] (optional), default value is 0.99

Specifies threshold for auto rotating image to correct orientation. Can be disabled with a value of 1 (see Auto rotation section for details).

rm_spaces bool (optional), default value is true

Determines whether extra white space is removed from equations in latex_styled and text formats.

See output option examples for the same equation returned with and without the spacing.

rm_fonts bool (optional), default value is false

Determines whether font commands such as \mathbf and \mathrm are removed from equations in latex_styled and text formats.

See output option examples for the same equation returned with and without the font commands.

idiomatic_eqn_arrays bool (optional), default value is false

Specifies whether to use aligned, gathered, or cases instead of an array environment for a list of equations.

See output option examples for a piecewise function returned as an array and as cases.

idiomatic_braces bool (optional), default value is false

Specifies whether to remove unnecessary braces for LaTeX output.

Example

x^2 is returned instead of x^{2}

See output option examples for the same equation returned with and without the braces.

numbers_default_to_math bool (optional), default value is false

Specifies whether numbers are always math.

Example

Answer: \( 17 \) instead of Answer: 17

See output option examples for the same text processed with this option off and on.

math_fonts_default_to_math bool (optional), default value is false

Specifies whether math fonts are always math.

Example

Answer: \( 2 \mathrm { ms } \) instead of Answer: 2 ms

math_inline_delimiters [string, string] (optional), default value is ["\\(", "\\)"]

Specifies begin inline math and end inline math delimiters for text outputs.

See output option examples for the same text returned with the default delimiters and with dollar signs.

math_display_delimiters [string, string] (optional), default value is ["\\[", "\\]"]

Specifies begin display math and end display math delimiters for text outputs.

See output option examples for the same equation returned with the default delimiters and with double dollar signs.

enable_spell_check bool (deprecated)

Deprecated, has no effect on the output.

enable_tables_fallback bool (deprecated)

Deprecated, accepted for backward compatibility but has no effect. Tables are always recognized with the table segmentation algorithm.

fullwidth_punctuation bool (optional), default value is null

Controls if punctuation will be fullwidth Unicode (default for east Asian languages like Chinese), or halfwidth Unicode (default for Latin scripts, Cyrillic scripts etc.). When null, fullwidth vs halfwidth will be decided based on image content. Punctuation inside math will always stay halfwidth.

See output option examples for the same Chinese text returned with fullwidth and with halfwidth punctuation.

Format descriptions

Format	Description
text	Mathpix Markdown
html	HTML rendered from text via mathpix-markdown-it
data	Data computed from text as specified in the data_options request parameter
latex_styled	Styled Latex, returned only in cases that the whole image can be reduced to a single equation

DataOptions object

Data options are used to return elements of the image output. These outputs are all computed from the text format described above. The data_options parameter must be an object - only the keys listed below are accepted. Unknown keys return opts_unknown_data_option.

include_svg bool (optional)

include math SVG in html and data formats

include_table_html bool (optional)

include HTML for html and data outputs (tables only)

include_latex bool (optional)

include math mode latex in data and html

include_tsv bool (optional)

include tab separated values (TSV) in data and html outputs (tables only)

include_asciimath bool (optional)

include asciimath in data and html outputs

include_mathml bool (optional)

include mathml in data and html outputs

include_sub_math bool (optional)

include sub-math elements in data and html outputs

Response body

request_id string

Request ID, for debugging purposes

text string (optional)

Recognized text format, if such is found. May contain custom Mathpix macros.

latex_styled string (optional)

Math LaTeX string of math equation, if the image is of a single equation. May contain custom Mathpix macros.

confidence number in [0,1] (optional)

Estimated probability 100% correct

confidence_rate number in [0,1] (optional)

Estimated confidence of output quality

line_data object[] (optional)

List of LineData objects

word_data object[] (optional)

List of WordData objects

data object[] (optional)

List of Data objects

html string (optional)

Annotated HTML output

detected_alphabets DetectedAlphabet[] (optional)

Detected alphabet flags

is_printed bool (optional)

Specifies if printed content was detected in an image

is_handwritten bool (optional)

Specifies if handwritten content was detected in an image

auto_rotate_confidence number in [0,1] (optional)

Estimated probability that image needs to be rotated, see Auto rotation

auto_rotate_degrees number in {0, 90, -90, 180} (optional)

Estimated angle of rotation in degrees to put image in correct orientation, see Auto rotation

image_height integer (optional)

Height of the processed image in pixels

image_width integer (optional)

Width of the processed image in pixels

error string (optional)

US locale error message

error_info ErrorInfo (optional)

Error info object

version string

This string is opaque to clients and only useful as a way of understanding differences in results for requests using the same image. Our service relies on training data, the service implementation, and the underlying platforms we run on (e.g., AWS, PyTorch). Initially, the version string will only change when the training data or process changes, but in the future we might provide more distinctions between versions.

Type definitions

Data object

Data objects allow extracting the math elements from an OCR result.

type string

one of asciimath, mathml, latex, svg, tsv

value string

value corresponding to type

LineData object

Returned when include_line_data is set to true. Contains information about all textual line elements detected in the image. Concatenating content from line_data recreates the top-level text, html, and data fields.

The OCR engine does not support some lines (like diagrams), which are skipped. Lines with extraneous content (like equation numbers) or low confidence have conversion_output set to false.

id string

Unique line identifier

parent_id string (optional)

Unique line identifier of the parent.

children_ids string[] (optional)

List of children unique identifiers.

type string

See line types and subtypes for details.

subtype string (optional)

See line types and subtypes for details.

cnt [[x,y]]

Contour for line expressed as list of (x,y) pixel coordinate pairs. For axis-aligned bounding boxes, vertices are in [TL, TR, BR, BL] order (clockwise from top-left)

included bool

Whether this line is included in the top level OCR result (deprecated, use conversion_output)

conversion_output boolean

Whether this line is included in the top level OCR result

is_printed bool

True if line has printed text, false otherwise.

is_handwritten bool

True if line has handwritten text, false otherwise.

error_id string (optional)

Error ID, reason why the line is not included in final result

text string (optional)

Text (Mathpix Markdown) for line

confidence number in [0,1] (optional)

Estimated probability 100% correct

confidence_rate number in [0,1] (optional)

Estimated confidence of output quality

after_hyphen bool (optional)

specifies if the current line occurs after the text line which ended with hyphen

html string (optional)

Annotated HTML output for the line

data Data[] (optional)

List of Data object's

Possible values for error_id:

• image_not_supported - OCR engine doesn't accept this line format
• image_max_size - line is larger than maximal size which OCR engine supports
• math_confidence - OCR engine failed to confidently recognize the content of the line
• image_no_content - line has strange spatial dimensions, e.g. height of the line is zero

Line data types and subtypes

Types and subtypes returned as part of line data and PDF lines data (types are the keys, subtypes are values):

{
  "chart_info": [],
  "x_axis_tick_label": [],
  "y_axis_tick_label": [],
  "x_axis_label": [],
  "y_axis_label": [],
  "legend_label": [],
  "model_label": [],
  "page_info": [
    "qr_code",
    "margin_note"
  ],
  "equation_number": [],
  "table": [],
  "diagram": [
    "algorithm",
    "pseudocode",
    "chemistry",
    "chemistry_reaction",
    "triangle"
  ],
  "chart": [
    "column",
    "bar",
    "line",
    "analytical",
    "pie",
    "scatter",
    "area"
  ],
  "diagram_info": [],
  "text": [
    "vertical",
    "big_capital_letter"
  ],
  "math": [],
  "column": [],
  "code": [],
  "pseudocode": [],
  "figure_label": [],
  "form_field": [
    "parentheses",
    "dotted",
    "dashed",
    "box",
    "checkbox",
    "circle"
  ],
  "qed_symbol": [],
  "multiple_choice_block": [],
  "multiple_choice_option": [],
  "footnote": [],
  "table_of_contents_container": [],
  "table_of_contents_row": [],
  "table_of_contents_item": [],
  "table_of_contents_number": [],
  "title": [],
  "quote": [],
  "section_header": [],
  "authors": [],
  "abstract": [],
  "rotated_container": [],
  "table_cell": [
    "split",
    "spanning"
  ]
}

WordData object

Returned when include_word_data is set to true. Contains information about all word-level elements detected in the image.

type string

One of text, math, table, diagram, equation_number

subtype string (optional)

Either not set, or chemistry, or triangle (more diagram subtypes coming soon)

cnt [[x,y]]

Contour for word expressed as list of (x,y) pixel coordinate pairs. For axis-aligned bounding boxes, vertices are in [TL, TR, BR, BL] order (clockwise from top-left)

text string (optional)

Text (Mathpix Markdown) for word

latex string (optional)

Math mode LaTeX (Mathpix Markdown) for word

confidence number in [0,1] (optional)

Estimated probability 100% correct

confidence_rate number in [0,1] (optional)

Estimated confidence of output quality

Auto rotation

The auto rotation feature detects when images are in the wrong orientation and corrects them before processing.

Control the confidence threshold with the auto_rotate_confidence_threshold request parameter (number in [0,1]). Default is 0.99, meaning the image is rotated only when the algorithm is 99% confident. Set to 1 to disable auto rotation.

The response includes:

• auto_rotate_confidence - confidence that the image needs rotation (number in [0,1], ~0 if correct, ~1 if rotated)
• auto_rotate_degrees - rotation angle applied (one of 0, 90, -90, 180)

Region layout quality

SuperNet-201 adds layout assessment to line_data entries when include_line_data is requested. layout_confidence, when present, estimates the reliability of that region's attempted structure and is separate from text confidence / confidence_rate. Scores are omitted where matching model calibration is unavailable; omission does not mean zero confidence.

parse_status is parsed, unavailable, or failed for this image-processing path. It describes the result, not a correctness guarantee. fallback_reason, when present, explains a layout failure. Page-level parse_status and fallback_count summarize outcomes. The response also includes page_confidence, whose layout_confidence is a nullable numeric prototype estimate; a failed structured extraction sets it to zero. The same object appears in lines_json when requested. Source-image preservation is a document-processing capability; /v3/text does not gain hosted crop URLs or a new fallback option.

{"line_data":[{"id":"line-1","type":"text","text":"Example","confidence":0.99,"layout_confidence":0.94,"parse_status":"parsed"}],"parse_status":"parsed","fallback_count":0,"page_confidence":{"confidence":0.94,"text_confidence":0.99,"layout_confidence":0.94,"method":"prototype_min_v1"}}

The scores are illustrative; layout_confidence is absent for model/region scopes without validated calibration.

Shared page-region output (lines_json)

For full-page recognition from an image, send:

{
  "src": "https://example.com/page.png",
  "enable_document_layout": true,
  "include_line_data": true
}

The response includes both the existing line_data and the new lines_json document. lines_json has the same region schema as one PDF page's lines document: image identity and dimensions, ordered regions, hierarchy, geometry, text and available quality metadata. It is a single page object, not the PDF download's multi-page wrapper. Example response excerpt:

{
  "text": "Hello",
  "lines_json": {
    "image_id": "request-image-id",
    "page": 1,
    "page_width": 1200,
    "page_height": 1600,
    "lines": [
      {
        "id": "region-1",
        "type": "text",
        "text": "Hello",
        "region": {"top_left_x": 20, "top_left_y": 30, "width": 200, "height": 40}
      }
    ]
  }
}

include_lines_json: true also returns this document in ordinary image mode without enabling document layout. A completed parse with no regions can return lines: [] alongside a no-content error. Coordinates describe the processed image frame, including rotation/cropping. Matching a PDF page requires the same source pixels and recognition options; this field does not add PDF rasterization, PDF hyperlink extraction or hosted crop delivery to the image endpoint. Existing line_data is not renamed or replaced.

Unified page and line confidence

Image lines_json and each PDF lines.json page use the same confidence contract. Every region has confidence, text_confidence, and layout_confidence; unknown or inapplicable values are null. The page contains a page_confidence object with the same three fields and method: "prototype_min_v1". Worker page summaries also expose this object.

{
  "page_confidence": {
    "confidence": 0.8,
    "text_confidence": 0.95,
    "layout_confidence": 0.8,
    "method": "prototype_min_v1"
  },
  "lines": [
    {
      "id": "line-1",
      "type": "text",
      "text": "Example",
      "confidence": 0.8,
      "text_confidence": 0.95,
      "layout_confidence": 0.8
    }
  ]
}

Numbers are illustrative. This first implementation supplies prototype reliability estimates, not validated correctness probabilities. Line text_confidence is the existing OCR confidence value. Layout uses model-matched calibrated confidence when available, otherwise its raw evidence as an explicitly provisional proxy. Combined confidence is the minimum of required layout and text components; it does not assume independent errors. Text-bearing leaves missing OCR evidence have unknown combined confidence. Non-text regions have text_confidence: null and use layout evidence alone. Structural parents do not duplicate their children's OCR evidence.

Page text confidence is the minimum across text-bearing leaves, or unknown if any such leaf lacks evidence. Page layout uses the root and nested segmentation pass assessment, rather than just returned lines. A failed or image-fallback structured extraction has combined/layout confidence zero; preserving pixels does not mean successful structured recognition. An empty page with no evidence has unknown confidence. These heuristics do not guarantee detection of omitted, repeated, or misordered content and are sensitive to page length. No reviewed joint calibration artifact ships with this change. The prototype does not change rejection/fallback thresholds.

Migration: lines_json.lines[*].confidence changes from OCR-only to combined confidence. Read text_confidence for its old meaning. Legacy image line_data, word confidence, top-level image OCR confidence, and confidence_rate retain their existing semantics. layout_score is removed from both the page and every region in lines_json; raw evidence remains in saved-page/internal layout diagnostics (and the legacy line_data contract). There is no duplicate top-level layout_confidence; page components live under page_confidence.