> ## Documentation Index
> Fetch the complete documentation index at: https://docs.somark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# OXR

> Learn how OXR converts PDFs and document images to Markdown and JSON with layout coordinates, and choose how to run it.

## What is OXR?

**OXR (Optical Everything Recognition)** is a document parsing model from SoMark with 1.3 billion parameters. Its source code and model weights are publicly available. It converts PDFs and document images into Markdown in reading order and JSON with layout coordinates. Use Markdown to index document content and JSON to locate the original text, tables, and formulas on the page.

> [card] [GitHub repository](https://github.com/SoMarkAI/OXR)
>
> View the README, source code, and parsing examples.

> [card] [OXR-1.0 model](https://huggingface.co/SoMarkAI/OXR-1.0)
>
> Download the BF16 model and bundled lightweight layout model.

## Ways to use OXR

* **Online demo**. Upload a PDF or image and compare the Markdown and layout boxes with the original page. [Open the online demo](https://free-oxr.somark.ai/)
* **Free API**. Submit files through the HTTP API, CLI, or SDK. [View the integration guide](#oxr-free-api)
* **Self-hosting**. Run the model on your own NVIDIA GPU server and submit files through the local web demo, HTTP API, or SoMark CLI. [View the self-hosting steps](#self-hosting)

## What OXR can parse

OXR defines 13 layout element types, including titles, body text, page headers and footers, footnotes, captions, figures, tables, math formulas, chemical equations, chemical structures, code blocks, and stamps. The default output filters out page headers and footers. [Full element and format list](https://github.com/SoMarkAI/OXR#why-oxr)

| Example documents | What you get |
| - | - |
| Academic papers and research reports | Body text in reading order, plus tables, footnotes, and LaTeX formulas |
| Chemistry materials and exam papers | Chemical equations in mhchem syntax, plus chemical structures in SMILES or as images |
| Reports and scans | HTML or Markdown tables and region coordinates for checking the source page |

## OXR Free API

The OXR Free API hosts the open-source OXR model. Upload a PDF or image to try it without signing up or requesting an API key.

### Connection settings

| Setting | Value |
| - | - |
| Base URL | `https://free-oxr.somark.ai/api/v1` |
| Authentication | You can omit `api_key` |
| File submission | Upload the file directly as `file` |
| File formats | PDF, PNG, JPG, JPEG, BMP, TIF, TIFF, and WebP |
| Limits per request | **10 MB and 20 pages** |
| Output formats | Returns Markdown and JSON by default |
| Request handling | Requests enter a queue and processing time may vary. If you receive HTTP `429`, wait for the current task to finish before retrying |

### Endpoints

Sync parsing returns the result in the same request. Async parsing returns a `task_id` first. Use it to query progress and retrieve the result.

| Endpoint | Request | Documentation |
| - | - | - |
| Sync parsing | `POST /parse/sync` | [Sync parsing](https://docs.somark.ai/en/open-source-tools/oxr/sync.md) |
| Async submission | `POST /parse/async` | [Submit task](https://docs.somark.ai/en/open-source-tools/oxr/async-submit.md) |
| Async result | `POST /parse/async_check` | [Check result](https://docs.somark.ai/en/open-source-tools/oxr/async-check.md) |

### Use the CLI or SDK

With the [SoMark CLI or SDK](https://docs.somark.ai/en/cli-sdk/index.md), set the base URL to the address above. For the CLI, you can set `--api-key` to `dummy`.

```bash theme={null}
somark --base-url https://free-oxr.somark.ai/api/v1 --api-key dummy \
  parse document.pdf --formats md,json --out ./parsed-output/
```

When switching from the SoMark API, see [SoMark and OXR integration differences](https://docs.somark.ai/en/open-source-tools/oxr/integration).

## Self-hosting

After deploying OXR on your own server, submit documents through the local web demo, HTTP API, or SoMark CLI.

### Prepare your deployment environment

Use a Linux host with an NVIDIA GPU that supports BF16, a CUDA 13.0-compatible driver, and Docker configured for `--gpus all`. The project recommends 24 GB on one GPU for low-concurrency testing and at least 48 GB on one GPU for long documents or higher concurrency. Use Python 3.12 to install the model download tool. [Deployment requirements and FAQ](https://github.com/SoMarkAI/OXR/blob/main/docs/FAQ.md)

### Download the models and start the service

Clone the OXR repository and download the complete `OXR-1.0` model directory. It includes the recognition model and the layout weights under `layout_analysis/`.

```bash theme={null}
git clone https://github.com/SoMarkAI/OXR.git
cd OXR
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U huggingface_hub
hf download SoMarkAI/OXR-1.0 --local-dir ./models/OXR-1.0
```

Build the image and run the container from the repository root. The container starts the recognition model, layout model, and document parsing API together.

```bash theme={null}
docker build -f docker/Dockerfile.allinone -t oxr-1.0 .
docker run --rm --gpus all --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$PWD/models/OXR-1.0:/models/oxr-model:ro" \
  oxr-1.0
```

Wait for the logs to report that the service is ready. On the deployment host, open `http://localhost:8000/demo` to try parsing, or `http://localhost:8000/docs` to inspect the API. This command binds the port to the host's loopback address.

### Call your self-hosted parsing API

Put `document.pdf` in your terminal's current directory and send a sync parsing request to the local service. The two `output_formats` fields request Markdown and JSON.

```bash theme={null}
curl --fail-with-body http://localhost:8000/v1/parse/sync \
  -F 'file=@document.pdf' \
  -F 'api_key=dummy' \
  -F 'output_formats=markdown' \
  -F 'output_formats=json'
```

When the response has `code: 0`, read Markdown from `data.result.outputs.markdown` and layout JSON from `data.result.outputs.json`.

To save the output directly to files, use the SoMark CLI. Set the **Base URL** to the local service's `/v1` and use `md,json` to select the output formats.

```bash theme={null}
python -m pip install somark

somark --base-url http://localhost:8000/v1 --api-key dummy \
  parse document.pdf --formats md,json --out ./parsed-output/
```

Use Markdown to read and search the content. Use element types and `bbox` coordinates in JSON to locate regions on the original page. Check which OXR endpoints and parameters are available when integrating with your application. [SoMark and OXR integration differences](https://docs.somark.ai/en/open-source-tools/oxr/integration)

### Run from source

To deploy the recognition and layout models separately, start both model services and enter their addresses in the document parsing service's configuration. [Official source deployment steps](https://github.com/SoMarkAI/OXR#122-run-from-source)

## Public benchmarks

![OXR-1.0 overall scores on the OmniDocBench, olmOCR-bench, and DocParsingBench leaderboards](https://mintcdn.com/soulcode-9c5983db/-0FjCS9t0Ocp6dgn/images/oxr/benchmark-leaderboards.png?fit=max\&auto=format\&n=-0FjCS9t0Ocp6dgn\&q=85\&s=d4f0ec91ca438f51608aabb12cf703cc)

In the October 5, 2026 snapshot, OXR-1.0 scored **97.18** on `OmniDocBench`, **87.84** on `olmOCR-bench`, and **87.76** on `DocParsingBench`, ranking first among the models shown in each comparison. [SoMark leaderboards](https://somark.ai/oxr#benchmark)

The project also ran a fixed 100-page OmniDocBench sample on one 96 GB NVIDIA RTX PRO 6000 Blackwell GPU. OXR processed about **0.99 pages per second** end to end, including layout analysis, recognition, and reading order. [Benchmark conditions and full results](https://github.com/SoMarkAI/OXR/blob/main/docs/benchmark.md)

OXR uses the OXR License, which is based on Apache 2.0 and includes additional commercial licensing and attribution terms. [Full license](https://github.com/SoMarkAI/OXR/blob/main/LICENSE)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.