> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 返回结构详解

> 了解文档解析 API 返回的 Elements、Markdown、坐标、表格结构等完整字段说明

文档解析 API 返回统一的 JSON 结构，包含文档的 Markdown 表示、结构化元素列表、页面元信息等。本文档详细说明返回结果的各个字段。

## 响应总览

```json theme={null}
{
  "code": 200,
  "message": "success",
  "data": {
    "schema_version": "1.3.0",
    "file_id": "doc_7f3a2b",
    "job_id": "job_x9k2m",
    "success_count": 5,
    "metadata": { ... },
    "markdown": "# 标题\n\n正文内容...",
    "elements": [ ... ],
    "title_tree": [ ... ],
    "pages": [ ... ],
    "summary": { ... }
  }
}
```

### 顶层字段

| 字段        | 类型     | 说明           |
| --------- | ------ | ------------ |
| `code`    | int    | 状态码，200 表示成功 |
| `message` | string | 状态信息         |
| `data`    | object | 解析结果数据       |

### data 字段

| 字段               | 类型     | 说明                         |
| ---------------- | ------ | -------------------------- |
| `schema_version` | string | 数据结构版本号，当前为 `"1.3.0"`      |
| `file_id`        | string | 文件唯一标识                     |
| `job_id`         | string | 任务唯一标识                     |
| `success_count`  | int    | 成功解析的页数（计费依据）              |
| `metadata`       | object | 文件元信息                      |
| `markdown`       | string | 文档的 Markdown 表示            |
| `elements`       | array  | 文档元素列表                     |
| `title_tree`     | array  | 文档目录树（需开启 `title_tree` 能力） |
| `pages`          | array  | 页面元信息列表（需开启 `pages` 能力）    |
| `summary`        | object | 处理耗时统计                     |

***

## metadata（文件元信息）

```json theme={null}
{
  "filename": "document.pdf",
  "filetype": "application/pdf",
  "page_count": 10,
  "data_source": {
    "record_locator": {
      "protocol": "file",
      "remote_file_path": "/path/to/document.pdf"
    },
    "url": "file:///path/to/document.pdf"
  }
}
```

| 字段            | 类型     | 说明               |
| ------------- | ------ | ---------------- |
| `filename`    | string | 文件名              |
| `filetype`    | string | 文件 MIME 类型       |
| `page_count`  | int    | 文档总页数            |
| `data_source` | object | 数据源详细信息，包含协议、路径等 |

***

## elements（文档元素）

`elements` 是解析结果的核心，每个元素代表文档中的一个结构化单元（标题、段落、表格、图片等）。

<Note>
  **GUI 引擎差异**：使用 `force_engine: "textin_gui"` 时，elements 结构有所不同，包含 GUI 专属字段和元素类型。详见 [GUI 识别引擎特别说明](#gui-识别引擎特别说明)。
</Note>

### 基本结构

```json theme={null}
{
  "element_id": "el_001",
  "type": "Title",
  "text": "第一章 概述",
  "page_number": 1,
  "coordinates": [0.100000, 0.120000, 0.320000, 0.120000, 0.320000, 0.160000, 0.100000, 0.160000],
  "metadata": {
    "category_depth": 0,
    "children_ids": ["el_002", "el_003"],
    "is_continuation": false,
    "data_source": {
      "record_locator": {
        "protocol": "file",
        "remote_file_path": "/path/to/document.pdf"
      },
      "url": "file:///path/to/document.pdf"
    }
  }
}
```

### 基础字段

| 字段                | 类型     | 说明                                                                                                                                         |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `element_id`      | string | 元素唯一标识                                                                                                                                     |
| `type`            | string | 元素类型（见下方类型表）                                                                                                                               |
| `sub_type`        | string | 元素子类型（可选），用于进一步细分。如 `Image` 可能有 `stamp`（印章）、`qrcode`（二维码）、`barcode`（条形码）、`chart`（图表）等子类型；`Table` 可能有 `bordered`（有框线）、`borderless`（无框线）等子类型 |
| `text`            | string | 元素文本内容                                                                                                                                     |
| `page_number`     | int    | 所在页码（从 1 开始）                                                                                                                               |
| `coordinates`     | array  | 四点坐标，归一化到 \[0, 1]，顺序为左上、右上、右下、左下                                                                                                           |
| `metadata`        | object | 元素元信息                                                                                                                                      |
| `objects`         | array  | 元素内的行内对象列表（需开启 `include_inline_objects`，见下文）                                                                                               |
| `table_structure` | object | 表格结构详情（仅 `Table` 元素，需开启 `include_table_structure`，见下文）                                                                                     |
| `char_details`    | array  | 字符级详细信息（需开启 `include_char_details`，见下文）                                                                                                    |
| `image_data`      | object | 图片数据（仅 `Image` 元素，需开启 `include_image_data`，见下文）                                                                                            |

<Tip>
  **GUI 引擎专属字段**：使用 GUI 引擎时，elements 还包含 `interactivity`（是否可交互）和 `description`（语义描述）字段。[查看详情](#gui-识别引擎特别说明)
</Tip>

### 元素类型

| 类型                  | 说明    |
| ------------------- | ----- |
| `Title`             | 标题    |
| `NarrativeText`     | 正文段落  |
| `ListItem`          | 列表项   |
| `Table`             | 表格    |
| `TableCaption`      | 表格标题  |
| `Image`             | 图片    |
| `FigureCaption`     | 图片标题  |
| `Formula`           | 数学公式  |
| `Chemical`          | 化学分子式 |
| `Header`            | 页眉    |
| `Footer`            | 页脚    |
| `PageNumber`        | 页码    |
| `PageBreak`         | 分页符   |
| `CodeSnippet`       | 代码片段  |
| `UncategorizedText` | 未分类文本 |

<Note>
  上述元素类型适用于文档解析引擎。**GUI 引擎使用不同的元素类型**（如 button, input, checkbox 等），详见 [GUI 元素类型](#ui-元素类型（type）)。
</Note>

### metadata 字段

| 字段                    | 类型     | 说明                                             |
| --------------------- | ------ | ---------------------------------------------- |
| `parent_id`           | string | 父元素 ID（需开启 `include_hierarchy`）                |
| `children_ids`        | array  | 子元素 ID 列表（需开启 `include_hierarchy`）             |
| `category_depth`      | int    | 同类型元素的嵌套深度（如 Title 的 0 为一级标题，1 为二级标题）          |
| `ref_element_id`      | string | 关联元素 ID，如图片/表格与其标题的关联（需开启 `include_hierarchy`） |
| `is_continuation`     | bool   | 是否为跨页续接的元素                                     |
| `continuation_of`     | string | 当 `is_continuation=true` 时，指向被续接的前一个元素 ID      |
| `has_inline_objects`  | bool   | 是否包含行内对象（需开启 `include_inline_objects`）         |
| `inline_object_types` | array  | 行内对象类型列表，如 `["formula", "handwriting"]`        |
| `width`               | int    | 图片宽度（仅 Image 元素）                               |
| `height`              | int    | 图片高度（仅 Image 元素）                               |
| `data_source`         | object | 数据源详细信息                                        |

***

## 坐标系统

坐标使用归一化的四点表示法，每个坐标值在 `[0, 1]` 范围内，表示相对于页面宽高的比例。

```
coordinates: [x1, y1, x2, y2, x3, y3, x4, y4]
```

四个点的顺序为：

```
(x1,y1) -------- (x2,y2)
   |                |
   |     元素区域    |
   |                |
(x4,y4) -------- (x3,y3)
```

坐标值保留六位小数，范围 \[0, 1]，表示相对于页面宽高的比例。要将归一化坐标转换为像素坐标，需要乘以页面的实际宽高：

```python theme={null}
# 假设页面宽 595px, 高 842px (A4)
page_width, page_height = 595, 842
pixel_x1 = coordinates[0] * page_width
pixel_y1 = coordinates[1] * page_height
```

***

## 表格结构（table\_structure）

当开启 `include_table_structure` 能力时，类型为 `Table` 的元素会包含 `table_structure` 字段。

```json theme={null}
{
  "element_id": "el_010",
  "type": "Table",
  "text": "| 姓名 | 年龄 |\n|---|---|\n| 张三 | 28 |",
  "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]
      },
      {
        "cell_id": "tbl_001_r1_c2",
        "row": 1,
        "col": 2,
        "row_span": 1,
        "col_span": 1,
        "content_type": "text",
        "text": "年龄",
        "coordinates": [0.300000, 0.300000, 0.500000, 0.300000, 0.500000, 0.340000, 0.300000, 0.340000]
      },
      {
        "cell_id": "tbl_001_r2_c1",
        "row": 2,
        "col": 1,
        "row_span": 1,
        "col_span": 1,
        "content_type": "text",
        "text": "张三",
        "coordinates": [0.100000, 0.340000, 0.300000, 0.340000, 0.300000, 0.380000, 0.100000, 0.380000]
      },
      {
        "cell_id": "tbl_001_r2_c2",
        "row": 2,
        "col": 2,
        "row_span": 1,
        "col_span": 1,
        "content_type": "text",
        "text": "28",
        "coordinates": [0.300000, 0.340000, 0.500000, 0.340000, 0.500000, 0.380000, 0.300000, 0.380000]
      }
    ]
  }
}
```

### 单元格字段

| 字段             | 类型     | 说明                                                                                                                |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------- |
| `cell_id`      | string | 单元格唯一标识                                                                                                           |
| `row`          | int    | 行索引（从 1 开始）                                                                                                       |
| `col`          | int    | 列索引（从 1 开始）                                                                                                       |
| `row_span`     | int    | 跨行数                                                                                                               |
| `col_span`     | int    | 跨列数                                                                                                               |
| `content_type` | string | 内容类型：`text`（文本）、`formula`（公式）、`image`（图片）、`mixed`（混合）                                                             |
| `text`         | string | 单元格文本                                                                                                             |
| `coordinates`  | array  | 单元格四点坐标                                                                                                           |
| `image_datas`  | array  | 图片数据数组（当 `content_type` 为 `image` 时，需开启 `include_image_data`）。了解版本差异请参考 [Schema 版本迁移指南](/xparse/schema-migration) |
| `objects`      | array  | 单元格内嵌对象列表（需开启 `include_inline_objects`）                                                                           |
| `char_details` | array  | 字符级详情（需开启 `include_char_details`）                                                                                 |

<Note>
  当请求参数 `element_merge_mode` 为 `merged` 时，合并后的单元格还会返回 `source_regions`、`role`、`header_cell_ids`、`text_source_ranges` 等跨页来源字段，详见[跨页表格合并](#单元格新增字段（merged-模式）)。
</Note>

***

## 跨页表格合并（merged 模式）

当一张表格被分页切断、跨越多个物理页时，可通过请求参数 `element_merge_mode` 选择输出方式。默认 `separate` 沿用按页输出，`merged` 则把同一张逻辑表合并为一个 Table 元素。

<Tip>
  `element_merge_mode` 的取值与配置方式，详见[解析配置详解](/xparse/v1/parse-config#element_merge_mode)。
</Tip>

### 两种模式对比

**`separate`（默认）**：每个物理分页分别返回一个 Table 片段，通过 `metadata.is_continuation` 和 `metadata.continuation_of` 建立续接关系。

```json theme={null}
[
  {
    "element_id": "table_fragment_p1",
    "type": "Table",
    "sub_type": "bordered",
    "text": "<table>...</table>",
    "page_number": 1,
    "coordinates": [0.1, 0.18, 0.9, 0.18, 0.9, 0.84, 0.1, 0.84],
    "metadata": { "is_continuation": false }
  },
  {
    "element_id": "table_fragment_p2",
    "type": "Table",
    "sub_type": "bordered",
    "text": "<table>...</table>",
    "page_number": 2,
    "coordinates": [0.1, 0.16, 0.9, 0.16, 0.9, 0.82, 0.1, 0.82],
    "metadata": { "is_continuation": true, "continuation_of": "table_fragment_p1" }
  }
]
```

**`merged`**：同一张逻辑跨页表只返回一个合并后的 Table，`text` 为完整表格 HTML（续页重复的表头只保留一份，跨页的 `rowspan`/`colspan` 合并为一个单元格），并通过 `metadata.source_regions` 记录各物理页的来源区域。合并后的 `is_continuation` 固定为 `false`，不返回 `continuation_of`。

```json theme={null}
{
  "element_id": "table_merged_7b9a5d",
  "type": "Table",
  "sub_type": "bordered",
  "text": "<table>...</table>",
  "page_number": 1,
  "coordinates": [0.1, 0.18, 0.9, 0.18, 0.9, 0.84, 0.1, 0.84],
  "metadata": {
    "is_continuation": false,
    "table_structure_status": "available",
    "table_layout": {
      "rows": 8,
      "cols": 4,
      "header_rows": [1]
    },
    "source_regions": [
      { "page_number": 1, "coordinates": [0.1, 0.18, 0.9, 0.18, 0.9, 0.84, 0.1, 0.84], "start_row": 1, "end_row": 4 },
      { "page_number": 2, "coordinates": [0.1, 0.16, 0.9, 0.16, 0.9, 0.82, 0.1, 0.82], "start_row": 5, "end_row": 8 }
    ]
  },
  "table_structure": {
    "rows": 8,
    "cols": 4,
    "cells": ["..."]
  }
}
```

<Note>
  `table_structure_status` 为 `available` 时，Table 必定带 `table_structure`（合并后的单元格结构，示例中的 `cells` 已省略，详见[单元格新增字段](#单元格新增字段（merged-模式）)）；为 `disabled` 或 `unavailable` 时则不返回 `table_structure`。
</Note>

<Note>
  合并后的 Table 顶层 `page_number` 与 `coordinates` 只表示表格首页的位置（即 `source_regions[0]`）。要获取表格跨越的全部页面及各页坐标，请读取 `metadata.source_regions`。
</Note>

### 表级新增字段（merged 模式）

`merged` 模式下，Table 元素的 `metadata` 会额外返回以下字段（无论是否开启 `include_table_structure`，`table_layout`、`source_regions`、`table_structure_status` 都必定返回）。

| 字段                             | 类型     | 说明                                                                                                                  |
| ------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------- |
| `table_layout`                 | object | 合并后表格的逻辑网格信息                                                                                                        |
| `table_layout.rows`            | int    | 合并表总行数（不含续页被去重的重复表头）                                                                                                |
| `table_layout.cols`            | int    | 合并表总列数                                                                                                              |
| `table_layout.header_rows`     | int\[] | 表头所在行号（1 起、去重、升序），可为空；多级表头列出全部表头行                                                                                   |
| `table_structure_status`       | string | 单元格结构状态：`available`（已生成，存在 `table_structure`）、`disabled`（未开启 `include_table_structure`）、`unavailable`（已请求但引擎无法可靠生成） |
| `source_regions`               | array  | 各物理页来源区域，按页码和阅读顺序排列                                                                                                 |
| `source_regions[].page_number` | int    | 物理页码（从 1 开始）                                                                                                        |
| `source_regions[].coordinates` | array  | 该页表格片段的归一化四点坐标                                                                                                      |
| `source_regions[].start_row`   | int    | 该片段贡献的首个合并表行号（1 起，闭区间）                                                                                              |
| `source_regions[].end_row`     | int    | 该片段贡献的末个合并表行号（1 起，闭区间）。各区间的行范围连续覆盖 `1` 到 `table_layout.rows`，互不重叠                                                   |

### 单元格新增字段（merged 模式）

`merged` 且开启 `include_table_structure` 时，合并后的单元格（Canonical Cell）在[单元格字段](#单元格字段)基础上，额外返回跨页来源信息：

| 字段                   | 类型     | 说明                                                                                                                                                                                                         |
| -------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source_regions`     | array  | 该单元格在各物理页的来源区域，每项含 `page_number` 和归一化 `coordinates`；跨页 `rowspan` 单元格可有多个区域                                                                                                                                 |
| `role`               | string | 单元格角色：`column_header`、`row_header`、`data`、`footer`；无法判断时可省略，此时可参照 `table_layout.header_rows` 判断是否表头                                                                                                        |
| `header_cell_ids`    | array  | 该单元格对应的表头单元格 ID 列表；多级表头或横跨多列时可引用多个；表头单元格自身为空或省略                                                                                                                                                            |
| `text_source_ranges` | array  | 把合并后 `text` 的字符区间映射回物理页。每项含 `start`/`end`（相对 `text` 的 `[start, end)` 半开区间，单位为 Unicode 码点）、`page_number`、`coordinates`；文本跨页的长单元格建议返回。多个区间按 `start` 升序且互不重叠；计算偏移前请勿对 `text` 做 trim、空白折叠或 Unicode 归一化，否则区间会错位 |

<Note>
  合并后单元格的 `coordinates` 只表示该单元格在首页的位置（即 `source_regions[0].coordinates`）。要获取单元格跨越的全部页面位置，请读取 `source_regions`。续页重复的表头不产生新单元格，其在各页出现的位置都并入同一个表头单元格的 `source_regions`。
</Note>

### Cell 关闭时（include\_table\_structure=false）

`merged` + `include_table_structure=false` 时不返回 `table_structure`，但 `table_layout` 和表级 `source_regions` 仍会返回，`table_structure_status` 为 `disabled`：

```json theme={null}
{
  "element_id": "table_merged_7b9a5d",
  "type": "Table",
  "sub_type": "bordered",
  "text": "<table>...</table>",
  "page_number": 1,
  "coordinates": [0.1, 0.18, 0.9, 0.18, 0.9, 0.84, 0.1, 0.84],
  "metadata": {
    "is_continuation": false,
    "table_structure_status": "disabled",
    "table_layout": { "rows": 12, "cols": 4, "header_rows": [1] },
    "source_regions": [
      { "page_number": 1, "coordinates": [0.1, 0.18, 0.9, 0.18, 0.9, 0.84, 0.1, 0.84], "start_row": 1, "end_row": 6 },
      { "page_number": 2, "coordinates": [0.1, 0.18, 0.9, 0.18, 0.9, 0.84, 0.1, 0.84], "start_row": 7, "end_row": 12 }
    ]
  }
}
```

此时仍可从 HTML 恢复逻辑行列，并按表级 `source_regions` 定位整段物理页区域；无法提供的是单元格级精确坐标、表头引用和字符级来源。

***

## 图片数据（image\_data）

当开启 `include_image_data` 能力时，类型为 `Image` 的元素会包含 `image_data` 字段。

```json theme={null}
{
  "element_id": "el_020",
  "type": "Image",
  "text": "",
  "image_data": {
    "image_url": "https://example.com/images/xxx.png",
    "mime_type": "image/png",
    "base64": "iVBORw0KGgoAAAANSUhEUg..."
  }
}
```

| 字段          | 类型     | 说明               |
| ----------- | ------ | ---------------- |
| `image_url` | string | 图片访问 URL         |
| `mime_type` | string | 图片 MIME 类型       |
| `base64`    | string | 图片 Base64 编码（可选） |

***

## 字符级详情（char\_details）

当开启 `include_char_details` 能力时，元素会包含 `char_details` 字段，提供字符级别的坐标和识别置信度。

```json theme={null}
{
  "element_id": "el_001",
  "type": "Title",
  "text": "概述",
  "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}
        ]
      }
    },
    {
      "index": 1,
      "text": "述",
      "coordinates": [0.140000, 0.120000, 0.180000, 0.120000, 0.180000, 0.160000, 0.140000, 0.160000],
      "recognition": {
        "confidence": 0.998,
        "candidates": [
          {"text": "述", "confidence": 0.998},
          {"text": "迹", "confidence": 0.002}
        ]
      }
    }
  ]
}
```

| 字段                       | 类型     | 说明          |
| ------------------------ | ------ | ----------- |
| `index`                  | int    | 字符在文本中的位置索引 |
| `text`                   | string | 字符文本        |
| `coordinates`            | array  | 字符四点坐标      |
| `recognition.confidence` | float  | 识别置信度 (0-1) |
| `recognition.candidates` | array  | 候选识别结果      |

***

## 行内对象（objects）

当开启 `include_inline_objects` 能力时，包含行内对象的元素会返回 `objects` 字段，标识文本中的公式、手写体、复选框等行内元素。

```json theme={null}
{
  "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"
      }
    }
  ]
}
```

| 字段            | 类型     | 说明                                                               |
| ------------- | ------ | ---------------------------------------------------------------- |
| `object_id`   | string | 对象唯一标识                                                           |
| `type`        | string | 对象类型：`formula`（公式）、`handwriting`（手写）、`checkbox`（复选框）、`image`（图片） |
| `sub_type`    | string | 对象子类型（可选）                                                        |
| `text`        | string | 对象文本内容                                                           |
| `text_range`  | array  | 对象在父元素文本中的位置 `[start, end)`，0-based 半开区间                         |
| `coordinates` | array  | 对象四点坐标                                                           |
| `image_data`  | object | 图片数据（当 `type` 为 `image` 时）                                       |
| `metadata`    | object | 对象元信息，如公式的 `display_mode`（`inline` 或 `display`）                  |

***

## 目录树（title\_tree）

当开启 `title_tree` 能力时，返回文档的层级目录结构：

```json theme={null}
{
  "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": []
        },
        {
          "element_id": "el_010",
          "title": "1.2 目标",
          "level": 2,
          "page_number": 2,
          "children": []
        }
      ]
    }
  ]
}
```

| 字段            | 类型     | 说明               |
| ------------- | ------ | ---------------- |
| `element_id`  | string | 对应 Title 元素的 ID  |
| `title`       | string | 标题文本             |
| `level`       | int    | 标题层级，1 为最高（一级标题） |
| `page_number` | int    | 所在页码             |
| `children`    | array  | 嵌套的子标题节点列表       |

***

## 页面信息（pages）

当开启 `pages` 能力时，返回每一页的元信息：

```json theme={null}
{
  "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"],
      "spanning_element_ids": ["table_merged_7b9a5d"],
      "dpi": 144,
      "angle": 0,
      "status": "Success"
    }
  ]
}
```

| 字段                     | 类型     | 说明                                                                                                                   |
| ---------------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| `page_number`          | int    | 页码（从 1 开始）                                                                                                           |
| `page_width`           | number | 页面宽度（像素）                                                                                                             |
| `page_height`          | number | 页面高度（像素）                                                                                                             |
| `page_image_url`       | string | 页面渲染图 URL                                                                                                            |
| `element_ids`          | array  | 该页包含的元素 ID 列表，顺序与页面内默认阅读顺序一致                                                                                         |
| `spanning_element_ids` | array  | 跨页元素 ID 列表（仅 `element_merge_mode=merged` 时返回）。合并后的跨页表格只在首个来源页的 `element_ids` 中出现一次，其余来源页通过本字段引用，不在 `element_ids` 中重复 |
| `dpi`                  | int    | 当前页转成图片所用的 DPI                                                                                                       |
| `angle`                | number | 页面旋转角度（0 度为正常阅读方向，顺时针旋转）                                                                                             |
| `status`               | string | 页面处理状态                                                                                                               |

***

## 格式转换结果（exports）

当请求中配置了 [`exports`](/xparse/v1/parse-config#exports（格式转换）) 时，响应的 `data` 中会返回 `exports` 数组，包含各导出任务的状态与文件信息。

```json theme={null}
{
  "data": {
    "schema_version": "1.3.1",
    "file_id": "doc_xxx",
    "markdown": "# 文档标题...",
    "elements": [],
    "pages": [],
    "exports": [
      {
        "format": "docx",
        "status": "success",
        "file": {
          "file_id": "8bb84607d83b0115.docx",
          "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
          "size": 174135,
          "expires_at": "2026-08-23T17:48:15+08:00"
        },
        "warnings": []
      }
    ]
  }
}
```

**`data.exports[]` 字段**：

| 字段         | 类型     | 说明                                                                     |
| ---------- | ------ | ---------------------------------------------------------------------- |
| `format`   | string | 导出格式：`docx` / `xlsx` / `pdf`                                           |
| `status`   | string | 单个导出任务状态：`success` / `fail`                                            |
| `file`     | object | `status=success` 时返回，含 `file_id` / `mime_type` / `size` / `expires_at` |
| `warnings` | array  | 非致命降级信息（如部分图片下载失败）                                                     |
| `error`    | object | `status=fail` 时返回错误信息（与 `file` 互斥）                                     |

<Note>
  响应顶层 `code=200` 仅表示解析请求成功；每个导出文件是否成功以 `exports[].status` 为准。单个导出失败不影响其他导出与解析结果。
</Note>

### 下载导出文件

使用 `exports[].file.file_id` 的**原值**（需带后缀，如 `8bb84607d83b0115.docx`）调用下载接口获取文件：

```
GET https://api.textin.com/export_file/download?file_id={file_id}
x-ti-app-id: YOUR_APP_ID
x-ti-secret-code: YOUR_SECRET
```

| 参数        | 说明                                      |
| --------- | --------------------------------------- |
| `file_id` | 解析响应里 `exports[].file.file_id` 的原值（含后缀） |

**响应**：直接返回文件**字节流**（HTTP 200，body 为文件二进制内容）。

<Warning>
  **下载约束**

  * **仅生成者可下载**：只能用生成该 `file_id` 的同一个 app 凭证下载，跨 app 下载返回 `404 image does not exist`。
  * `file_id` 有过期时间（见 `expires_at`），过期后不可下载。
  * 下载相关的错误码排查见[常见错误码](#常见错误码)。
</Warning>

***

## 处理摘要（summary）

返回本次解析的耗时统计：

```json theme={null}
{
  "summary": {
    "duration_ms": 812
  }
}
```

| 字段            | 类型     | 说明      |
| ------------- | ------ | ------- |
| `duration_ms` | number | 总耗时（毫秒） |

***

## 错误响应

当 `code` 不为 200 时，表示请求出错。错误响应可能包含 `location` 字段，用于定位错误发生的位置：

```json theme={null}
{
  "code": 40004,
  "message": "参数错误，请查看技术文档，检查传参",
  "location": {
    "stage": "parse",
    "page_number": 3,
    "element_id": "el_045"
  }
}
```

| 字段            | 类型     | 说明      |
| ------------- | ------ | ------- |
| `stage`       | string | 出错阶段    |
| `page_number` | int    | 出错页码    |
| `element_id`  | string | 出错元素 ID |

### 常见错误码

| 错误码   | HTTP 状态码 | 说明                                                                   |
| ----- | -------- | -------------------------------------------------------------------- |
| 40101 | 200      | x-ti-app-id 或 x-ti-secret-code 为空                                    |
| 40102 | 200      | x-ti-app-id 或 x-ti-secret-code 无效，验证失败                               |
| 40103 | 200      | 客户端IP不在白名单                                                           |
| 40003 | 200      | 余额不足，请充值后再使用                                                         |
| 40004 | 200      | 参数错误，请查看技术文档，检查传参                                                    |
| 40007 | 200      | 机器人不存在或未发布                                                           |
| 40008 | 200      | 机器人未开通，请至市场开通后重试                                                     |
| 40301 | 200      | 图片类型不支持                                                              |
| 40302 | 200      | 上传文件大小不符，文件大小不超过 500M                                                |
| 40303 | 200      | 文件类型不支持，接口会返回实际检测到的文件类型，如"当前文件类型为.gif"                               |
| 40304 | 200      | 图片尺寸不符，长宽比小于2的图片宽高需在20～20000像素范围内，其他图片的宽高需在20～10000像素范围内             |
| 40305 | 200      | 识别文件未上传                                                              |
| 40306 | 200      | qps超过限制                                                              |
| 40307 | 200      | 今日免费额度已用完                                                            |
| 40422 | 200      | 文件损坏（The file is corrupted.）                                         |
| 40423 | 200      | PDF密码错误（Password required or incorrect password.）                    |
| 40424 | 200      | 页数设置超出文件范围（Page number out of range.）                                |
| 40425 | 200      | 文件格式不支持（The input file format is not supported.）                     |
| 40427 | 200      | DPI参数不在支持列表中（Input DPI is not in the allowed DPIs list(72,144,216).） |
| 40428 | 200      | word和ppt转pdf失败或者超时（Process office file failed.）                      |
| 40429 | 200      | 不支持的引擎（Unsupported Engine.）                                          |
| 50207 | 200      | 部分页面解析失败（Partial failed）                                             |
| 40400 | 200      | 无效的请求链接，请检查链接是否正确                                                    |
| 30203 | 200      | 基础服务故障，请稍后重试                                                         |
| 500   | 200      | 服务器内部错误                                                              |

<Tip>
  遇到错误时，可以通过响应头中的 `x-request-id` 联系技术支持排查问题。
</Tip>

**格式转换下载接口相关错误码**：

| 错误码   | 说明                     | 排查方向                                                  |
| ----- | ---------------------- | ----------------------------------------------------- |
| 200   | 请求成功                   | 导出是否成功以 `exports[].status` 为准                         |
| 400   | 参数错误                   | 检查 `config` 的 JSON 格式是否合法；下载接口需传入 `file_id` 参数且值含文件后缀 |
| 40101 | app-id 为空              | 请求未携带鉴权 Header                                        |
| 40102 | app-id / secret 无效     | 凭证错误；若解析接口调用正常、仅下载接口返回此错误，说明该 app 未在下载接口注册，请联系技术支持开通  |
| 404   | `image does not exist` | `file_id` 已过期（见 `expires_at`），或使用了非生成者的 app 凭证下载      |

<Note>
  导出任务自身的失败（如某个格式生成失败）不体现在错误码里，而是通过 `exports[].status` 为 `fail` 及其 `error` 字段返回。详见[格式转换结果](#格式转换结果（exports）)。
</Note>

***

## GUI 识别引擎特别说明

使用 `force_engine: "textin_gui"` 时，返回结构与普通文档解析基本一致，但 `elements` 的 `type` 字段值和 `metadata` 字段内容有所不同。

<Note>
  GUI 引擎仅支持图片格式输入（JPEG、PNG、GIF、WebP），文件大小不超过 10MB，不支持 PDF 等文档格式。配置方法详见 [解析配置 - force\_engine](/xparse/v1/parse-config#force_engine)。
</Note>

### 基本结构

```json theme={null}
{
  "element_id": "el_001",
  "type": "button",
  "text": "登录",
  "page_number": 1,
  "coordinates": [0.450000, 0.600000, 0.550000, 0.600000, 0.550000, 0.640000, 0.450000, 0.640000],
  "metadata": {
    "parent_id": "el_000",
    "children_ids": [],
    "is_continuation": false,
    "interactivity": true,
    "description": "登录按钮",
    "data_source": {
      "record_locator": {
        "protocol": "file",
        "remote_file_path": "/path/to/screenshot.png"
      },
      "url": "file:///path/to/screenshot.png"
    }
  }
}
```

### 基础字段

与文档解析引擎相同，包含以下字段：

| 字段            | 类型     | 说明                            |
| ------------- | ------ | ----------------------------- |
| `element_id`  | string | 元素唯一标识，同其他引擎                  |
| `type`        | string | **UI 元素类型**（见下方类型表，与文档解析引擎不同） |
| `text`        | string | 元素的可见文本/标签内容，同其他引擎            |
| `page_number` | int    | 所在页码（从 1 开始），同其他引擎            |
| `coordinates` | array  | 坐标信息，同其他引擎                    |
| `metadata`    | object | 元素元信息（**包含 GUI 专属字段**，见下方）    |

### UI 元素类型（type）

与文档解析引擎不同，GUI 引擎返回的 `type` 为 UI 组件类型：

| 元素类型         | 说明   | 示例          |
| ------------ | ---- | ----------- |
| `button`     | 按钮   | 提交按钮、关闭按钮   |
| `input`      | 输入框  | 文本框、密码框、搜索框 |
| `checkbox`   | 复选框  | 多选框         |
| `dropdown`   | 下拉菜单 | 选择器、下拉列表    |
| `link`       | 链接   | 超链接、导航链接    |
| `tab`        | 标签页  | 选项卡         |
| `text`       | 静态文本 | 标签文本、说明文字   |
| `label`      | 标签   | 表单标签、分类标签   |
| `title`      | 标题   | 窗口标题、区域标题   |
| `icon`       | 图标   | 功能图标、状态图标   |
| `image`      | 图片   | 缩略图、背景图     |
| `menu`       | 菜单   | 导航菜单、上下文菜单  |
| `navigation` | 导航栏  | 顶部导航、侧边导航   |
| `toolbar`    | 工具栏  | 操作工具栏       |
| `statusbar`  | 状态栏  | 底部状态栏       |

### metadata 字段

GUI 引擎的 `metadata` 包含与文档解析引擎相同的通用字段（parent\_id、children\_ids、is\_continuation、data\_source 等），以及以下专属字段：

| 字段              | 类型     | 说明      |
| --------------- | ------ | ------- |
| `interactivity` | bool   | 是否可交互   |
| `description`   | string | 元素的语义描述 |

***

## 相关链接

<CardGroup cols={2}>
  <Card title="快速入门" icon="rocket" href="/xparse/v1/quickstart">
    从零开始完成第一次文档解析
  </Card>

  <Card title="解析配置详解" icon="sliders" href="/xparse/v1/parse-config">
    深入了解所有输入参数配置，自定义解析行为
  </Card>

  <Card title="API 参考" icon="book" href="/api-reference/endpoint/xparse/v1/parse-sync">
    完整的请求参数与响应 Schema
  </Card>

  <Card title="Python SDK" icon="python" href="/xparse/v1/sdk-python">
    SDK 高级用法与最佳实践
  </Card>
</CardGroup>