> ## 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.
# 同步解析
> 上传文件并立即获取解析结果
路径变更：该接口路径已从 `/extract/acc_sync` 更改为 `/parse/sync`。旧路径将于 `2026-12-31` 停用，请在此之前迁移至新路径。
请求参数变更：`extract_config` 已更名为 `feature_config`。请将请求中的 `extract_config` 字段替换为 `feature_config`。
| 可选输出格式 | 默认值 | 说明 |
| --------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `json` / `markdown` / `zip` | `["markdown", "json"]` | **可多选** ，不传时使用默认值；`zip` 将 Markdown 和所有图片文件打包为压缩包；在 `output_formats` 包含 `zip` 时，`element_formats.image` 只能是 `file` |
| 配置项 | 可选输出格式 | 默认值 | 说明 |
| --------- | ---------------------------------- | ------- | -------------------------------------------------------------- |
| `image` | `url` / `base64` / `file` / `none` | `url` | **单选**，image 设定为`file`时，`output_formats`需包含`zip`；`none`表示不返回图片 |
| `formula` | `latex` / `mathml` / `ascii` | `latex` | **单选**，指定公式的输出格式 |
| `table` | `markdown` / `html` / `image` | `html` | **单选**，`markdown` 模式下，合并单元格将自动拆分为独立单元格，并以相同内容填充 |
| `cs` | `image` | `image` | **单选**，化学结构式输出格式，即将支持`smiles`格式 |
| 配置项 | 默认值 | 说明 |
| -------------------------------- | ------- | ---------------------------------- |
| `enable_text_cross_page` | `false` | **文字跨页拼接**：跨页文字段合并为连续段落 |
| `enable_table_cross_page` | `false` | **表格跨页拼接**：跨页表格合并为完整表格 |
| `enable_title_level_recognition` | `false` | **标题层级识别**：识别文档标题层级结构（H1/H2/H3...） |
| `enable_inline_image` | `false` | **文中图**：返回文字段落中的图片 |
| `enable_table_image` | `true` | **表中图**：返回表格单元格内的图片 |
| `enable_image_understanding` | `true` | **图片理解**：对文档内图片进行语义理解和结构化描述 |
| `keep_header_footer` | `false` | **保留页眉页脚**：默认过滤了页眉页脚，如果使用页眉页脚可开启保留 |
如果你需要了解鉴权、使用限制和同步/异步选择建议，先看 [API 概览](/api-reference/index)。大文件、批处理和后台任务建议改走 [异步解析 — 提交任务](/api-reference/endpoint/async-submit)。
## OpenAPI
````yaml POST /parse/sync
openapi: 3.0.3
info:
title: SoMark 文档智能 API
description: >-
SoMark 文档解析服务 API，支持 PDF、图片、Word、PPT 和 Excel 文件解析，输出 Markdown / JSON / DOCX
格式。
version: 1.0.0
servers:
- url: https://somark.cn/api/v1
security: []
paths:
/parse/sync:
post:
summary: 同步解析
description: 上传文件并同步等待解析结果，解析完成后一次性返回。
operationId: parseSync
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- api_key
properties:
file:
type: string
format: binary
description: 待解析的文件，支持 PDF、图片、Word、PPT 和 Excel 格式
output_formats:
type: array
items:
type: string
enum:
- json
- markdown
- zip
default:
- markdown
- json
description: >-
输出格式，可多选。不传时默认为 ["markdown", "json"]。支持 json / markdown /
zip，其中 zip 将所有输出文件打包为压缩包
api_key:
type: string
description: API 密钥，格式 sk-***
element_formats:
type: object
description: 元素格式配置，控制各类元素的格式
properties:
image:
type: string
enum:
- url
- base64
- none
default: url
description: 图片格式
formula:
type: string
enum:
- latex
- mathml
- ascii
default: latex
description: 公式格式
table:
type: string
enum:
- markdown
- html
- image
default: html
description: 表格格式
cs:
type: string
enum:
- image
default: image
description: 化学结构式格式
feature_config:
type: object
description: 特色功能配置（参数已从 extract_config 更名为 feature_config）
properties:
enable_text_cross_page:
type: boolean
default: false
description: 文字跨页拼接
enable_table_cross_page:
type: boolean
default: false
description: 表格跨页拼接
enable_title_level_recognition:
type: boolean
default: false
description: 标题层级识别
enable_inline_image:
type: boolean
default: false
description: 返回文中图
enable_table_image:
type: boolean
default: true
description: 返回表中图
enable_image_understanding:
type: boolean
default: true
description: 图片理解
keep_header_footer:
type: boolean
default: false
description: 保留页眉页脚
responses:
'200':
description: 解析成功
content:
application/json:
schema:
$ref: '#/components/schemas/ExtractSyncResponse'
x-codeSamples:
- lang: python
label: Python
source: |-
import json
import requests
url = "https://somark.cn/api/v1/parse/sync"
data = {
"output_formats": ["markdown", "json"],
"api_key": "sk-***",
"element_formats": json.dumps({
"image": "url",
"formula": "latex",
"table": "html",
"cs": "image",
}),
"feature_config": json.dumps({
"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,
"keep_header_footer": False,
}),
}
files = {"file": ("example.pdf", open("example.pdf", "rb"))}
response = requests.post(url, data=data, files=files)
print(response.json())
- lang: bash
label: cURL
source: |-
curl -X POST https://somark.cn/api/v1/parse/sync \
-F "file=@example.pdf" \
-F "output_formats=markdown" \
-F "output_formats=json" \
-F "api_key=sk-***" \
-F 'element_formats={"image":"url","formula":"latex","table":"html","cs":"image"}' \
-F 'feature_config={"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,"keep_header_footer":false}'
components:
schemas:
ExtractSyncResponse:
type: object
properties:
code:
type: integer
description: 状态码，`0` 为成功，非 `0` 见[错误码](/api-reference/errors)
example: 0
message:
type: string
example: 任务成功
data:
type: object
properties:
task_id:
type: string
description: 任务 ID
example: a1b2c3d4e5f6
error:
nullable: true
description: 错误信息，成功时为 null
metadata:
type: object
properties:
page_num:
type: integer
description: 文件总页数
example: 10
file_type:
type: string
description: 文件类型
example: .pdf
result:
type: object
properties:
file_name:
type: string
description: 解析的文件名
example: document.pdf
outputs:
type: object
properties:
markdown:
type: string
description: Markdown 格式全文
example: |-
# 标题
正文内容...
json:
type: object
description: JSON 格式输出
properties:
pages:
type: array
description: 逐页结构化解析结果
items:
type: object
properties:
page_num:
type: integer
description: 页码，从 0 开始
example: 0
blocks:
type: array
description: 当前页中的内容块，按阅读顺序排列
items:
type: object
properties:
idx:
type: integer
description: 块索引
example: 0
type:
type: string
description: 元素类型标识符
example: title
bbox:
type: array
description: 块坐标范围，格式为 [x1, y1, x2, y2]
items:
type: integer
example:
- 72
- 50
- 540
- 80
content:
type: string
description: 块内容
example: 第一章 引言
format:
type: string
description: 块内容格式
example: text
captions:
type: array
description: 关联图注块 idx 列表
items:
type: integer
example:
- 0
img_url:
type: string
description: 图片资源地址
example: string
title_level:
type: integer
nullable: true
description: >-
标题层级（1=H1, 2=H2, 3=H3...）。仅当 `type` 为
`title` 且开启
`enable_title_level_recognition` 时出现
example: 1
text_cross_page:
type: object
nullable: true
description: >-
跨页文字引用信息。仅当开启 `enable_text_cross_page`
且该块为跨页续接时出现
properties:
page_num:
type: integer
description: 来源页码
block_idx:
type: integer
description: 来源块索引
table_cross_page:
type: object
nullable: true
description: >-
跨页表格引用信息。仅当开启 `enable_table_cross_page`
且该块为跨页续接时出现
properties:
page_num:
type: integer
description: 来源页码
block_idx:
type: integer
description: 来源块索引
target_has_header:
type: boolean
description: 目标表格是否包含表头
page_size:
type: object
properties:
h:
type: integer
description: 页面高度
example: 1684
w:
type: integer
description: 页面宽度
example: 1190
merge_content_from_pre_page:
type: boolean
description: >-
是否将上一页末尾内容合并到当前页开头（需开启
feature_config.enable_text_cross_page）
example: true
example:
pages:
- page_num: 0
blocks:
- idx: 0
type: title
bbox:
- 72
- 50
- 540
- 80
content: 第一章 引言
format: text
captions: []
img_url: ''
title_level: 1
- idx: 1
type: text
bbox:
- 72
- 100
- 540
- 200
content: 本文档介绍了...
format: text
captions: []
img_url: ''
page_size:
h: 1684
w: 1190
merge_content_from_pre_page: false
zip:
type: string
description: ZIP 压缩包下载地址
example: https://example.com/result.zip
example:
code: 0
message: 任务成功
data:
task_id: a1b2c3d4e5f6
error: null
metadata:
page_num: 10
file_type: .pdf
result:
file_name: document.pdf
outputs:
markdown: |-
# 第一章 引言
本文档介绍了...
json:
pages:
- page_num: 0
blocks:
- idx: 0
type: title
bbox:
- 72
- 50
- 540
- 80
content: 第一章 引言
format: text
captions: []
img_url: ''
title_level: 1
- idx: 1
type: text
bbox:
- 72
- 100
- 540
- 200
content: 本文档介绍了...
format: text
captions: []
img_url: ''
page_size:
h: 1684
w: 1190
merge_content_from_pre_page: false
````