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

# 接口对齐

> 以 SoMark API 为基准，对照 OXR 支持与不支持的接口和参数

以 [SoMark API](/api-reference/index) 为基准，列出 OXR（Free API 与自部署）的支持情况。

> [!NOTE]
>
> 图例：✅ 支持　⚠️ 部分支持或行为不同　❌ 不支持

## 接口

| 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 独有参数](#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 暂未开放 |

> [!WARNING]
>
> `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` | ❌ | 图内文字识别 |

> [!NOTE]
>
> 不支持的 `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` | ✅ | ❌ |

> [!NOTE]
>
> 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` | 参数被忽略时给出提示 |

> **[返回概览](/api-reference/oxr/index)**
>
> 了解 OXR 与 SoMark 的关系及 Free API 使用方式


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