> ## 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-元素类型)。
</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`）                                                                                 |

***

## 图片数据（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"],
      "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 列表，顺序与页面内默认阅读顺序一致 |
| `dpi`            | int    | 当前页转成图片所用的 DPI               |
| `angle`          | number | 页面旋转角度（0 度为正常阅读方向，顺时针旋转）     |
| `status`         | string | 页面处理状态                       |

***

## 处理摘要（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>

***

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