API alignment

This page uses the SoMark API as the baseline and lists what OXR (Free API and self-hosted) supports.

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_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

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

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

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`	✅	❌

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

Learn how OXR relates to SoMark and how to use the Free API

API Overview

Document Parsing

PDF to Office

OXR Free API

Endpoints

Common request parameters

output_formats

element_formats

feature_config

OXR-only parameters

extra

File formats

Usage limits

Response differences

Back to overview

​Endpoints

​Common request parameters

​output_formats

​element_formats

​feature_config

​OXR-only parameters

​extra

​File formats

​Usage limits

​Response differences

Back to overview

Endpoints

Common request parameters

output_formats

element_formats

feature_config

OXR-only parameters

extra

File formats

Usage limits

Response differences