解析配置详解

文档解析 API 支持通过 config 参数自定义解析行为。本文档详细说明所有可用的配置项。

配置结构总览

{
  "document": {
    "password": "example-pdf-password"
  },
  "capabilities": {
    "include_hierarchy": true,
    "include_inline_objects": false,
    "include_char_details": false,
    "include_image_data": false,
    "include_table_structure": false,
    "element_merge_mode": "separate",
    "pages": false,
    "title_tree": false,
    "table_view": "html",
    "remove_watermark": false,
    "crop_dewarp": false
  },
  "scope": {
    "page_range": "1-5"
  },
  "config": {
    "force_engine": "textin",
    "engine_params": {
      "parse_mode": "vlm",
      "formula_level": 0,
      "image_output_type": "url",
      "recognize_chemical": true
    }
  },
  "exports": [
    {
      "format": "docx",
      "config": {
        "mode": "flow"
      }
    }
  ]
}

document（文档相关配置）

配置文档本身的处理参数。

{
  "document": {
    "password": "example-pdf-password"
  }
}

字段	类型	必填	说明
`password`	string	否	加密文档的密码（如加密的 PDF 文件）

使用场景：

处理受密码保护的 PDF 文档
确保加密文档能够正常解析

capabilities（解析策略与格式配置）

控制返回数据的详细程度和格式。开启更多能力会增加解析耗时和返回数据量。

include_hierarchy

是否返回元素间的层级与关联字段。

字段	类型	默认值	说明
`include_hierarchy`	boolean	`true`	开启后，返回元素间的父子关系、引用关系等信息

开启后返回的字段：

parent_id：父元素 ID
children_ids：子元素 ID 列表
ref_element_id：关联元素 ID（如图片/表格与其标题的关联）

使用场景：

需要构建文档的结构化关系图谱
需要理解元素之间的从属关系
需要追踪标题与内容的层级关系

{
  "capabilities": {
    "include_hierarchy": true
  }
}

include_inline_objects

是否返回细粒度的行内对象。

字段	类型	默认值	说明
`include_inline_objects`	boolean	`false`	开启后，文本类元素会返回其中包含的细粒度对象

支持的行内对象类型：

formula：数学公式（LaTeX 格式）
handwriting：手写内容
checkbox：复选框
image：内嵌图片

使用场景：

需要精确定位和提取公式
需要识别手写签名或批注
需要处理表单中的复选框
需要提取文本段落中的内嵌图片

{
  "capabilities": {
    "include_inline_objects": true
  }
}

返回示例：

{
  "element_id": "el_004",
  "type": "NarrativeText",
  "text": "设违约金函数 $f(x)=x^2+1$ 。",
  "objects": [
    {
      "object_id": "obj_001",
      "type": "formula",
      "text": "$f(x)=x^2+1$",
      "text_range": [7, 20],
      "coordinates": [0.220000, 0.480000, 0.300000, 0.480000, 0.300000, 0.540000, 0.220000, 0.540000],
      "metadata": {
        "display_mode": "inline"
      }
    }
  ]
}

include_char_details

是否返回字符级详细信息。

字段	类型	默认值	说明
`include_char_details`	boolean	`false`	开启后，返回文本中每个字符的详细信息

返回的字符信息包括：

字符坐标
识别置信度
候选字符列表

使用场景：

需要字符级别的精确定位
需要评估识别质量
需要处理低置信度字符
需要实现字符级别的纠错

{
  "capabilities": {
    "include_char_details": true
  }
}

返回示例：

{
  "char_details": [
    {
      "index": 0,
      "text": "概",
      "coordinates": [0.100000, 0.120000, 0.140000, 0.120000, 0.140000, 0.160000, 0.100000, 0.160000],
      "recognition": {
        "confidence": 0.999,
        "candidates": [
          {"text": "概", "confidence": 0.999},
          {"text": "槪", "confidence": 0.001}
        ]
      }
    }
  ]
}

include_image_data

是否返回图片数据。

字段	类型	默认值	说明
`include_image_data`	boolean	`false`	开启后，图片元素将返回完整的图片数据

返回的图片信息包括：

图片 URL
MIME 类型
Base64 编码（可选）

使用场景：

需要下载或显示文档中的图片
需要对图片进行二次处理
需要获取图片的 Base64 编码用于嵌入

{
  "capabilities": {
    "include_image_data": true
  }
}

返回示例：

{
  "element_id": "el_020",
  "type": "Image",
  "image_data": {
    "image_url": "https://example.com/images/xxx.png",
    "mime_type": "image/png",
    "base64": "iVBORw0KGgoAAAANSUhEUg..."
  }
}

include_table_structure

是否返回表格的详细结构化信息。

字段	类型	默认值	说明
`include_table_structure`	boolean	`false`	开启后，以 JSON 格式返回表格的行、列以及每个单元格的详细信息

返回的表格结构包括：

行数和列数
每个单元格的位置（行、列）
单元格的跨行跨列信息
单元格内容类型（文本、公式、图片、混合）
单元格坐标

使用场景：

需要程序化处理表格数据
需要提取表格单元格的精确位置
需要处理复杂表格（合并单元格）
需要识别表格单元格中的公式或图片

{
  "capabilities": {
    "include_table_structure": true
  }
}

返回示例：

{
  "element_id": "el_010",
  "type": "Table",
  "table_structure": {
    "rows": 2,
    "cols": 2,
    "cells": [
      {
        "cell_id": "tbl_001_r1_c1",
        "row": 1,
        "col": 1,
        "row_span": 1,
        "col_span": 1,
        "content_type": "text",
        "text": "姓名",
        "coordinates": [0.100000, 0.300000, 0.300000, 0.300000, 0.300000, 0.340000, 0.100000, 0.340000]
      }
    ]
  }
}

element_merge_mode

控制跨页表格的输出方式：按物理页分别输出，还是合并为一个逻辑表格。

字段	类型	默认值	可选值	说明
`element_merge_mode`	string	`separate`	`separate`, `merged`	控制跨页表格按物理页分别输出，或合并为一个逻辑 Table

两种模式的行为：

separate：每个物理分页分别返回一个 Table 片段（fragment），通过 metadata.is_continuation 和 metadata.continuation_of 保留跨页续接关系。
merged：同一张逻辑跨页表只返回一个合并后的 Table（Canonical Table），text 为完整的表格 HTML，并通过 source_regions 记录每个物理页的来源区域。
单页表格在两种模式下输出一致。

使用场景：

需要把跨页表格连续渲染为一张完整表格时，使用 merged
需要按物理页逐页定位、逐页处理表格片段时，使用 separate

{
  "capabilities": {
    "element_merge_mode": "merged"
  }
}

与 include_table_structure 的组合：两个参数相互独立，可自由组合。

`element_merge_mode`	`include_table_structure`	输出
`separate`	`false`	每页一个 Table 片段，不返回单元格结构
`separate`	`true`	每页一个 Table 片段，各自返回单元格结构
`merged`	`false`	一个合并后的 Table，返回完整 HTML、`table_layout` 和表级 `source_regions`
`merged`	`true`	一个合并后的 Table，并返回合并后的单元格结构及单元格来源映射

table_view 只控制 data.markdown 中表格的表达格式，不影响 elements[] 的跨页输出模式。

pages

是否返回页面元信息列表。

字段	类型	默认值	说明
`pages`	boolean	`false`	开启后，返回每一页的详细信息

返回的页面信息包括：

页码
页面宽高
旋转角度
渲染图片地址（page_image_url）
包含的元素列表（element_ids）
DPI
处理状态

使用场景：

需要按页面组织文档内容
需要获取页面的预览图
需要了解页面的物理属性（宽高、DPI）
需要定位某个元素所在的页面

{
  "capabilities": {
    "pages": true
  }
}

返回示例：

{
  "pages": [
    {
      "page_number": 1,
      "page_width": 1576,
      "page_height": 1683,
      "page_image_url": "https://example.com/page-1.jpg",
      "element_ids": ["el_001", "el_002", "el_003"],
      "dpi": 144,
      "angle": 0,
      "status": "Success"
    }
  ]
}

title_tree

是否返回标题树（目录）。

字段	类型	默认值	说明
`title_tree`	boolean	`false`	开启后，返回文档的层级目录结构

返回的目录信息包括：

标题文本
标题层级（1 为最高级）
所在页码
嵌套的子标题

使用场景：

需要生成文档目录导航
需要按章节组织内容
需要理解文档的大纲结构

{
  "capabilities": {
    "title_tree": true
  }
}

返回示例：

{
  "title_tree": [
    {
      "element_id": "el_001",
      "title": "第一章 概述",
      "level": 1,
      "page_number": 1,
      "children": [
        {
          "element_id": "el_005",
          "title": "1.1 背景",
          "level": 2,
          "page_number": 1,
          "children": []
        }
      ]
    }
  ]
}

table_view

表格在 Markdown 中的表达格式。

字段	类型	默认值	可选值	说明
`table_view`	string	`"html"`	`markdown`, `html`	控制 Markdown 字段中表格的渲染格式

格式对比： Markdown 格式（table_view: "markdown"）：

| 姓名 | 年龄 |
|---|---|
| 张三 | 28 |

HTML 格式（table_view: "html"）：

<table>
  <thead>
    <tr><th>姓名</th><th>年龄</th></tr>
  </thead>
  <tbody>
    <tr><td>张三</td><td>28</td></tr>
  </tbody>
</table>

使用场景：

需要简洁的 Markdown 表格格式
需要支持复杂表格结构（合并单元格）时使用 HTML

remove_watermark（去水印）

是否对文档进行去水印预处理。

字段	类型	默认值	说明
`remove_watermark`	boolean	`false`	开启后，自动检测并去除文档中的水印

使用场景：

去除文档中的水印干扰，提升识别准确率
获取无水印的干净解析结果

{
  "capabilities": {
    "remove_watermark": true
  }
}

crop_dewarp（切边矫正）

是否对文档进行切边矫正预处理。

字段	类型	默认值	说明
`crop_dewarp`	boolean	`false`	开启后，自动检测并对文档进行切边矫正预处理

使用场景：

扫描文档存在多余边框或页面倾斜
拍照文档存在透视畸变（如书页弯曲）
需要获得正向、紧凑的页面图像，提升版面分析质量

{
  "capabilities": {
    "crop_dewarp": true
  }
}

scope（处理范围控制）

控制解析的页面范围，减少不必要的处理。

{
  "scope": {
    "page_range": "1-5,10-15"
  }
}

字段	类型	必填	说明
`page_range`	string	否	页码范围，从 1 开始，支持多个闭区间

格式说明：

单页："1"
连续页："1-5"
多个区间："1-2,3-4,5-10"

单文件页数限制说明当文件页数超过请求限制时，API 将返回错误。请参考以下限制和解决方案：

用户类型	同步接口限制	异步接口限制	可用解决方案
免费用户	≤100 页	≤100 页	① 使用 `page_range` 参数分段处理 ② 升级为付费用户 ③ 改用异步 API
付费用户	≤500 页	≤2000 页	① 使用 `page_range` 参数分段处理 ② 若文件超过 500 页，建议改用异步 API
企业客户	≤500 页	≤5000 页	① 使用 `page_range` 参数分段处理 ② 若文件超过 500 页，建议改用异步 API

使用场景：

仅处理文档的特定页面
减少处理时间和成本
分批处理大型文档

exports（格式转换）

在解析文档的同时，额外将结果导出为 docx / xlsx / pdf 文件。解析结果（markdown / elements / pages）与导出文件在同一次请求内返回，各导出任务独立成败、互不影响。

不传 exports 时，响应与原解析接口完全一致（向后兼容）。导出文件通过下载接口获取，具体见返回结构详解 - 格式转换结果。

{
  "document": { "password": "加密文档密码" },
  "scope": { "page_range": "1-10" },
  "config": { "force_engine": "textin", "engine_params": {} },
  "exports": [
    { "format": "docx", "config": { "mode": "flow" } },
    { "format": "xlsx", "config": { "scope": "table", "sheet_mode": "multi" } },
    { "format": "pdf",  "config": { "mode": "layout" } }
  ]
}

字段	必填	说明
`exports[].format`	是	文件格式：`docx` / `xlsx` / `pdf`（每种格式最多出现一次）
`exports[].config`	否	按格式区分的导出配置，缺省字段使用默认值

各格式配置项：

格式	配置项	取值	默认
docx	`mode`	`flow` / `layout`	`flow`
xlsx	`scope`	`document`（全部元素）/ `table`（仅表格）	`document`
xlsx	`sheet_mode`	`multi` / `single`	`multi`
pdf	`mode`	`layout`	`layout`

xlsx 分表逻辑（scope × sheet_mode）：

scope	sheet_mode	行为
`table`	`multi`	每个表格一个 Sheet
`table`	`single`	所有表格放入同一个 Sheet
`document`	`multi`	每页一个 Sheet（文本段落 + 表格）
`document`	`single`	全部内容放入同一个 Sheet

使用场景：

解析后直接获得可下载的 Word / Excel / PDF 文件，无需自行二次转换
将表格批量导出为 Excel 便于数据处理
还原文档版面生成 PDF 用于归档或分享

config（高级配置）

专家模式配置，用于强制指定解析引擎和引擎参数。

谨慎使用：这些配置仅供专业用户使用。不当的配置可能导致解析质量下降或失败。

force_engine

强制指定内部解析引擎。

字段	类型	可选值	说明
`force_engine`	string	`textin`, `textin_gui`	强制使用特定的解析引擎

引擎说明：

textin：TextIn 自研引擎，默认选项，综合性能最佳
textin_gui：GUI 识别引擎，用于桌面/移动/网页应用界面截图识别

textin_gui 仅支持图片格式（JPEG、PNG、GIF、WebP），文件大小不超过 10MB，且返回结构有差异。详见 GUI 识别引擎特别说明

使用场景：

对比不同引擎的效果
特定场景下需要使用特定引擎
调试和测试

{
  "config": {
    "force_engine": "textin"
  }
}

engine_params

引擎级自定义参数，不同引擎支持的参数不同。

字段	类型	说明
`engine_params`	object	传递给解析引擎的自定义参数

常用参数示例：

{
  "config": {
    "force_engine": "textin",
    "engine_params": {
      "parse_mode": "parse",
      "formula_level": 0,
      "image_output_type": "url",
      "recognize_chemical": true
    }
  }
}

参数	类型	可选值	说明
`parse_mode`	string	`auto`, `scan`, `parse`, `lite`, `vlm`	PDF 解析模式。 • `auto`：由引擎自动选择，适用范围最广 • `scan`：全当图片解析 • `parse`：仅电子档文字解析，速度最快 • `lite`：轻量版，只输出表格和文字结果 • `vlm`：视觉语言模型解析模式
`formula_level`	int	`0`, `1`	公式识别级别，0 为标准，1 为增强
`image_output_type`	string	`url`, `base64`	图片输出类型，`url` 或 `base64`
`recognize_chemical`	boolean	`true`, `false`	获取文档中的化学分子式结构，仅在`vlm`模式下生效，打开后可在元素的 text 中查看结果

不同引擎支持的参数可能不同，具体参数请联系技术支持获取。

完整配置示例

基础配置（推荐）

适用于大多数场景的默认配置：

{
  "capabilities": {
    "include_hierarchy": true,
    "title_tree": true,
    "include_table_structure": true
  }
}

最大化详细信息

返回所有可用的详细信息（会增加处理时间和数据量）：

{
  "capabilities": {
    "include_hierarchy": true,
    "include_inline_objects": true,
    "include_char_details": true,
    "include_image_data": true,
    "include_table_structure": true,
    "pages": true,
    "title_tree": true,
    "table_view": "html"
  }
}

最小化配置

仅返回基本的元素和 Markdown：

{
  "capabilities": {
    "include_hierarchy": false
  }
}

处理加密 PDF

{
  "document": {
    "password": "your-pdf-password"
  },
  "capabilities": {
    "include_hierarchy": true,
    "title_tree": true
  }
}

仅处理前 10 页

{
  "scope": {
    "page_range": "1-10"
  },
  "capabilities": {
    "include_hierarchy": true
  }
}

性能优化建议

按需开启能力

只开启必需的能力开关，避免返回不必要的数据。例如，如果不需要字符级详情，就不要开启 include_char_details。

合理使用 page_range

对于大文档，可以先处理部分页面进行测试，确认效果后再处理全部页面。

异步处理大文件

对于超过 50 页的文档，建议使用异步 API，避免 HTTP 超时。

缓存处理结果

相同文档的重复处理会产生相同的 file_id，可以通过 file_id 实现结果缓存。

快速入门

5 分钟完成第一次文档解析

返回结构详解

了解完整的返回数据结构

API 参考

完整的 API 参数与响应 Schema

异步解析

使用异步 API 处理大文件

产品概览

文档解析新版

文档解析

文档抽取

FAQ

配置结构总览

document（文档相关配置）

capabilities（解析策略与格式配置）

include_hierarchy

include_inline_objects

include_char_details

include_image_data

include_table_structure

element_merge_mode

pages

title_tree

table_view

remove_watermark（去水印）

crop_dewarp（切边矫正）

scope（处理范围控制）

exports（格式转换）

config（高级配置）

force_engine

engine_params

完整配置示例

基础配置（推荐）

最大化详细信息

最小化配置

处理加密 PDF

仅处理前 10 页

性能优化建议

相关链接

快速入门

返回结构详解

API 参考

异步解析

​配置结构总览

​document（文档相关配置）

​capabilities（解析策略与格式配置）

​include_hierarchy

​include_inline_objects

​include_char_details

​include_image_data

​include_table_structure

​element_merge_mode

​pages

​title_tree

​table_view

​remove_watermark（去水印）

​crop_dewarp（切边矫正）

​scope（处理范围控制）

​exports（格式转换）

​config（高级配置）

​force_engine

​engine_params

​完整配置示例

​基础配置（推荐）

​最大化详细信息

​最小化配置

​处理加密 PDF

​仅处理前 10 页

​性能优化建议

​相关链接

快速入门

返回结构详解

API 参考

异步解析

配置结构总览

document（文档相关配置）

capabilities（解析策略与格式配置）

include_hierarchy

include_inline_objects

include_char_details

include_image_data

include_table_structure

element_merge_mode

pages

title_tree

table_view

remove_watermark（去水印）

crop_dewarp（切边矫正）

scope（处理范围控制）

exports（格式转换）

config（高级配置）

force_engine

engine_params

完整配置示例

基础配置（推荐）

最大化详细信息

最小化配置

处理加密 PDF

仅处理前 10 页

性能优化建议

相关链接