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

# Overview

> OXR is SoMark's open-source document parsing model, with a free API compatible with the SoMark API, CLI, and SDK

## What is OXR

OXR (Optical Everything Recognition) is SoMark's open-source, state-of-the-art document parsing model with 1.3B parameters. It parses PDFs and document images into agent-friendly data (Markdown / JSON) and returns layout analysis results.

> **[OXR on GitHub](https://github.com/SoMarkAI/OXR)**
>
> Source code, Docker deployment, and model downloads

> **[Online demo](https://free-oxr.somark.ai)**
>
> Upload a document and see the parsing result, no sign-up needed

## Relationship with SoMark

SoMark is a commercial document intelligence service. OXR is the open-source parsing model and service from the SoMark team. They share the same API conventions, so the SoMark ecosystem works with OXR services:

* A self-hosted OXR and the Free OXR API both work with the official SoMark [CLI & SDK](/en/cli-sdk/index) (`somark-py`, `somark-js`). Just replace the **Base URL**.
* Paths, parameter names, and response structure match the [SoMark API](/en/api-reference/index).

> [!WARNING]
>
> OXR only implements the core parsing capabilities. Some advanced parameters are not available, such as cross-page merging, title level recognition, `zip` output, and PDF to Office. These parameters are ignored or rejected with a parameter error. See [API alignment](/en/api-reference/oxr/alignment) for the full comparison.

## Free API

OXR provides a free API so you can test parsing on your own documents without registering or requesting an API key. We will keep it online until we can no longer afford to run it.

> [!WARNING]
>
> Do not use the Free OXR API in production. We do not guarantee service stability, and requests are queued, so processing speed may vary.

| | somark.ai | somark.cn |
| - | - | - |
| Online demo | [https://free-oxr.somark.ai](https://free-oxr.somark.ai) | [https://free-oxr.somark.cn](https://free-oxr.somark.cn) |
| API URL | `https://free-oxr.somark.ai/api/v1` | `https://free-oxr.somark.cn/api/v1` |
| API docs | [https://docs.somark.ai/api-reference](https://docs.somark.ai/api-reference) | [https://docs.somark.cn/api-reference](https://docs.somark.cn/api-reference) |

> [!NOTE]
>
> `somark.cn` mirrors `somark.ai`. Pick whichever fits your region.

### Upload limits

> **File size**
>
> Up to **10MB** per file

> **Page count**
>
> Up to **20 pages** per request

Files over these limits are rejected. For larger or longer documents, use [SoMark production](/en/api-reference/index) (200MB, 300 pages) or self-host OXR.

### Usage

The Free OXR API requires no authentication. Set `api_key` to any value, such as `dummy`.

```bash CLI theme={null}
# Python
pip install somark
# or JS
npm install -g somark-js

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

```bash cURL theme={null}
curl --fail-with-body https://free-oxr.somark.ai/api/v1/parse/sync \
  -F 'file=@document.pdf' \
  -F 'api_key=dummy' \
  -F 'output_formats=markdown' \
  -F 'output_formats=json'
```

## Self-hosted OXR

You can deploy OXR with Docker on your own GPU server. Use `http://<host>:8000/v1` as the Base URL. The 10MB / 20-page limits do not apply. See the [OXR repository](https://github.com/SoMarkAI/OXR) for deployment steps.

> **[API alignment](/en/api-reference/oxr/alignment)**
>
> See the parameter-by-parameter comparison between OXR and SoMark

## Star OXR on GitHub ⭐

[![Star OXR on GitHub](https://raw.githubusercontent.com/SoMarkAI/image_bed/main/OXR_README/assets/OXR_Star_on_GitHub.gif)](https://github.com/SoMarkAI/OXR)

> [!TIP]
>
> OXR is fully open source, and the team pays for the free API out of pocket. If it helps you, drop a ⭐ Star on GitHub. It is the best encouragement for the developers, and it keeps the free API alive longer.

> **[Star OXR on GitHub](https://github.com/SoMarkAI/OXR)**
>
> github.com/SoMarkAI/OXR


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