接口对齐

以 SoMark API 为基准，列出 OXR（Free API 与自部署）的支持情况。

图例：✅ 支持　⚠️ 部分支持或行为不同　❌ 不支持

接口

SoMark 接口	路径	OXR	说明
同步解析	`POST /parse/sync`	✅
异步解析：提交任务	`POST /parse/async`	✅
异步解析：结果查询	`POST /parse/async_check`	✅	任务保存在服务内存中，服务重启后丢失
PDF 转 Office（同步）	`POST /convert/sync`	❌	未实现
PDF 转 Office（异步）	`POST /convert/async`、`/convert/async_check`	❌	未实现
用量查询	`POST /usage`	❌	未实现，无额度和账号体系

通用请求参数

适用于 /parse/sync 和 /parse/async。

参数	OXR	说明
`file`	✅	必填，仅支持 PDF 和常见图片，见文件格式
`file_url`	❌	不支持通过链接提交，请直接上传 `file`
`api_key`	⚠️	字段必须存在，但不校验，可填任意值（如 `dummy`）
`output_formats`	⚠️	见下方
`element_formats`	⚠️	见下方
`feature_config`	⚠️	仅支持 `keep_header_footer`，见下方
`extra`	OXR 独有	模型采样参数，见OXR 独有参数

output_formats

取值	OXR	说明
`markdown`	✅
`json`	✅
`zip`	❌	返回参数错误

默认值与 SoMark 相同：["markdown", "json"]。

element_formats

配置项	取值	OXR	说明
`image`	`url`	✅	默认值
	`base64`	✅
	`none`	✅
	`file`	❌	依赖 `zip` 输出，返回参数错误
`formula`	`latex`	✅	默认值
	`mathml`	❌	返回参数错误
	`ascii`	❌	返回参数错误
`table`	`html`	✅	默认值
	`markdown`	✅
	`image`	❌	返回参数错误
`cs`	`image`	✅	SoMark 默认值
	`smiles`	✅	OXR 默认值，SoMark 暂未开放

cs 的默认值不同：不传时 SoMark 返回 image，OXR 返回 smiles。需要图片请显式传 {"cs": "image"}。

feature_config

配置项	SoMark 默认值	OXR	说明
`keep_header_footer`	`false`	✅	保留页眉页脚
`enable_text_cross_page`	`false`	❌	文字跨页拼接
`enable_table_cross_page`	`false`	❌	表格跨页拼接
`enable_title_level_recognition`	`false`	❌	标题层级识别
`enable_inline_image`	`false`	❌	文中图片还原
`enable_table_image`	`true`	❌	表中图片还原
`enable_image_understanding`	`true`	❌	图片理解
`enable_image_ocr`	`false`	❌	图内文字识别

不支持的 enable_* 配置项传入 true 时，请求不会失败，OXR 会忽略它，并在响应的 warnings 中给出提示。传入非布尔值会返回参数错误。

OXR 独有参数

extra

可选，JSON 对象，用于调整模型采样参数。SoMark 没有此参数，传入未列出的键会返回参数错误。

键	取值范围
`temperature`	`0` ~ `2`
`top_p`	`0` ~ `1`
`repetition_penalty`	大于 `0`

文件格式

类型	SoMark	OXR
`pdf`	✅	✅
`png` `jpg` `jpeg` `bmp` `tiff` `webp` 等常见图片	✅	✅
`gif` `heic` `heif` 等	✅	❌
`doc` `docx` `ppt` `pptx` `xls` `xlsx` `xlsm`	✅	❌

OXR 的图片格式取决于服务端 OpenCV 能否解码。Office 文件请先转换为 PDF 再提交。无法解析的文件会返回“无效文档”错误。

使用限制

项目	SoMark 正式版	Free OXR API	自部署 OXR
文件大小	200MB	10MB	不限制
页数	300 页	20 页	不限制
鉴权	需要 API 密钥	无需	无需
调用频率	QPS 4	排队处理，无保证	取决于部署资源

响应差异

响应结构与 SoMark 一致（code、message、warnings、data），差异如下：

项目	OXR
`data.metadata`	包含 `page_num`、`file_type`、`processing_time_ms`，字段比 SoMark 少
异步任务 `record_id`	始终为 `null`
异步任务状态	与 SoMark 一致，提交后为 `queuing`，完成为 `success`，失败为 `failed`
参数错误	`code` 为 `1133`，`message` 中列出全部错误项
解析失败	`code` 为 `1137`
`warnings`	参数被忽略时给出提示

返回概览

了解 OXR 与 SoMark 的关系及 Free API 使用方式

API 概览

文档智能解析

PDF 转 Office

OXR Free API

接口

通用请求参数

output_formats

element_formats

feature_config

OXR 独有参数

extra

文件格式

使用限制

响应差异

返回概览

​接口

​通用请求参数

​output_formats

​element_formats

​feature_config

​OXR 独有参数

​extra

​文件格式

​使用限制

​响应差异

返回概览

接口

通用请求参数

output_formats

element_formats

feature_config

OXR 独有参数

extra

文件格式

使用限制

响应差异