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

# 概览

> OXR 是 SoMark 开源的文档解析模型，提供免费 API，并与 SoMark API、CLI 和 SDK 兼容

## OXR 是什么

OXR（Optical Everything Recognition）是 SoMark 团队开源的 SOTA 文档解析模型，参数量 1.3B，可将 PDF 和文档图片解析为 Agent-Friendly 数据（Markdown / JSON），并提供版面分析结果。

> **[OXR on GitHub](https://github.com/SoMarkAI/OXR)**
>
> 源码、Docker 部署和模型下载

> **[在线 Demo](https://free-oxr.somark.cn)**
>
> 无需注册，上传文档即可查看解析效果

## 和 SoMark 的关系

SoMark 是商业化的文档智能解析服务，OXR 是 SoMark 团队开源的解析模型与服务。两者共用同一套 API 约定，所以 SoMark 生态完全兼容 OXR 的服务：

* 自部署的 OXR 和 Free OXR API，都可以直接使用 SoMark 官方的 [CLI & SDK](/cli-sdk/index)（`somark-py`、`somark-js`），只需替换 **Base URL**。
* 请求路径、参数名称和响应结构与 [SoMark API](/api-reference/index) 保持一致。

> [!WARNING]
>
> OXR 只实现了解析相关的基础能力。部分高级功能的参数在 OXR 中不可用，例如跨页拼接、标题层级识别、`zip` 输出、PDF 转 Office 等。传入这些参数会被忽略或返回参数错误。逐项对照见[接口对齐](/api-reference/oxr/alignment)。

## Free API

OXR 提供免费 API，无需注册或申请 API 密钥，即可用自己的文档测试解析效果。我们会持续提供免费 API 服务，直至服务器无法承受压力。

> [!WARNING]
>
> 不建议将 Free OXR API 用于线上环境。我们不保证服务稳定性，请求会排队处理，处理速度可能有所浮动。

| | 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 地址 | `https://free-oxr.somark.ai/api/v1` | `https://free-oxr.somark.cn/api/v1` |
| 对接文档 | [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` 是 `somark.ai` 的镜像，可以根据所在地区自行选择。

### 上传限制

> **文件大小**
>
> 单文件最大 **10MB**

> **文档页数**
>
> 单次最多 **20 页**

超出限制的文件会被拒绝。需要处理更大或更长的文档，请使用 [SoMark 正式版](/api-reference/index)（最大 200MB、300 页），或自部署 OXR。

### 使用方式

Free OXR API 无需鉴权，`api_key` 字段可填任意值（如 `dummy`）。

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

somark --base-url https://free-oxr.somark.cn/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.cn/api/v1/parse/sync \
  -F 'file=@document.pdf' \
  -F 'api_key=dummy' \
  -F 'output_formats=markdown' \
  -F 'output_formats=json'
```

## 自部署 OXR

OXR 可以通过 Docker 部署在自己的 GPU 服务器上，部署后同样使用 `http://<host>:8000/v1` 作为 Base URL，没有 10MB / 20 页的限制。部署步骤见 [OXR 仓库](https://github.com/SoMarkAI/OXR)。

> **[接口对齐](/api-reference/oxr/alignment)**
>
> 查看 OXR 与 SoMark 接口、参数的逐项对照表

## 给 OXR 点个 Star ⭐

[![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 完全开源，免费 API 也由团队自费维护。如果它帮到了你，请到 GitHub 点一颗 ⭐ Star，这是对开发者最大的鼓励，也能让免费 API 活得更久。

> **[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.