> ## 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.

# API alignment

> Which SoMark endpoints and parameters OXR supports, compared side by side

This page uses the [SoMark API](/en/api-reference/index) as the baseline and lists what OXR (Free API and self-hosted) supports.

> [!NOTE]
>
> Legend: ✅ supported　⚠️ partially supported or behaves differently　❌ not supported

## Endpoints

| SoMark endpoint | Path | OXR | Notes |
| - | - | :-: | - |
| Sync parsing | `POST /parse/sync` | ✅ | |
| Async parsing: submit | `POST /parse/async` | ✅ | |
| Async parsing: query result | `POST /parse/async_check` | ✅ | Tasks live in server memory and are lost on restart |
| PDF to Office (sync) | `POST /convert/sync` | ❌ | Not implemented |
| PDF to Office (async) | `POST /convert/async`, `/convert/async_check` | ❌ | Not implemented |
| Usage query | `POST /usage` | ❌ | Not implemented; there is no quota or account system |

## Common request parameters

Applies to `/parse/sync` and `/parse/async`.

| Parameter | OXR | Notes |
| - | :-: | - |
| `file` | ✅ | Required. PDF and common images only, see [File formats](#file-formats) |
| `file_url` | ❌ | URL submission is not supported. Upload `file` directly |
| `api_key` | ⚠️ | The field must be present but is not validated. Any value works (such as `dummy`) |
| `output_formats` | ⚠️ | See below |
| `element_formats` | ⚠️ | See below |
| `feature_config` | ⚠️ | Only `keep_header_footer` is supported, see below |
| `extra` | OXR only | Model sampling options, see [OXR-only parameters](#oxr-only-parameters) |

### output\_formats

| Value | OXR | Notes |
| - | :-: | - |
| `markdown` | ✅ | |
| `json` | ✅ | |
| `zip` | ❌ | Returns a parameter error |

The default matches SoMark: `["markdown", "json"]`.

### element\_formats

| Option | Value | OXR | Notes |
| - | - | :-: | - |
| `image` | `url` | ✅ | Default |
| | `base64` | ✅ | |
| | `none` | ✅ | |
| | `file` | ❌ | Requires `zip` output. Returns a parameter error |
| `formula` | `latex` | ✅ | Default |
| | `mathml` | ❌ | Returns a parameter error |
| | `ascii` | ❌ | Returns a parameter error |
| `table` | `html` | ✅ | Default |
| | `markdown` | ✅ | |
| | `image` | ❌ | Returns a parameter error |
| `cs` | `image` | ✅ | SoMark default |
| | `smiles` | ✅ | OXR default. Not yet available on SoMark |

> [!WARNING]
>
> The default for `cs` differs: when omitted, SoMark returns `image` and OXR returns `smiles`. Pass `{"cs": "image"}` explicitly if you need images.

### feature\_config

| Option | SoMark default | OXR | Notes |
| - | :-: | :-: | - |
| `keep_header_footer` | `false` | ✅ | Keep headers and footers |
| `enable_text_cross_page` | `false` | ❌ | Cross-page text merging |
| `enable_table_cross_page` | `false` | ❌ | Cross-page table merging |
| `enable_title_level_recognition` | `false` | ❌ | Title level recognition |
| `enable_inline_image` | `false` | ❌ | Inline image restoration |
| `enable_table_image` | `true` | ❌ | Table image restoration |
| `enable_image_understanding` | `true` | ❌ | Image understanding |
| `enable_image_ocr` | `false` | ❌ | Text recognition inside images |

> [!NOTE]
>
> Passing `true` for an unsupported `enable_*` option does not fail the request. OXR ignores it and adds a message to `warnings` in the response. A non-boolean value returns a parameter error.

## OXR-only parameters

### extra

Optional JSON object for tuning model sampling. SoMark has no such parameter. Unlisted keys return a parameter error.

| Key | Range |
| - | - |
| `temperature` | `0` to `2` |
| `top_p` | `0` to `1` |
| `repetition_penalty` | Greater than `0` |

## File formats

| Type | SoMark | OXR |
| - | :-: | :-: |
| `pdf` | ✅ | ✅ |
| `png` `jpg` `jpeg` `bmp` `tiff` `webp` and other common images | ✅ | ✅ |
| `gif` `heic` `heif` and similar | ✅ | ❌ |
| `doc` `docx` `ppt` `pptx` `xls` `xlsx` `xlsm` | ✅ | ❌ |

> [!NOTE]
>
> OXR's image support depends on what the server's OpenCV can decode. Convert Office files to PDF before submitting. Files that cannot be decoded return an "invalid document" error.

## Usage limits

| Item | SoMark production | Free OXR API | Self-hosted OXR |
| - | - | - | - |
| File size | 200MB | **10MB** | No limit |
| Pages | 300 | **20** | No limit |
| Authentication | API key required | None | None |
| Rate limit | QPS 4 | Queued, no guarantee | Depends on your resources |

## Response differences

The response structure matches SoMark (`code`, `message`, `warnings`, `data`). The differences are:

| Item | OXR |
| - | - |
| `data.metadata` | Contains `page_num`, `file_type`, and `processing_time_ms`, fewer fields than SoMark |
| Async `record_id` | Always `null` |
| Async task status | Same as SoMark: `queuing` after submission, `success` when done, `failed` on error |
| Parameter errors | `code` is `1133`, and `message` lists every error |
| Parsing failures | `code` is `1137` |
| `warnings` | Notes which parameters were ignored |

> **[Back to overview](/en/api-reference/oxr/index)**
>
> Learn how OXR relates to SoMark and how to use the Free API


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