返回结构详解 - Textin 智能文档解析

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

响应总览

{
  "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（文件元信息）

{
  "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 是解析结果的核心，每个元素代表文档中的一个结构化单元（标题、段落、表格、图片等）。

GUI 引擎差异：使用 force_engine: "textin_gui" 时，elements 结构有所不同，包含 GUI 专属字段和元素类型。详见 GUI 识别引擎特别说明。

基本结构

{
  "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`，见下文）

GUI 引擎专属字段：使用 GUI 引擎时，elements 还包含 interactivity（是否可交互）和 description（语义描述）字段。查看详情

元素类型

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

上述元素类型适用于文档解析引擎。GUI 引擎使用不同的元素类型（如 button, input, checkbox 等），详见 GUI 元素类型。

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]，表示相对于页面宽高的比例。要将归一化坐标转换为像素坐标，需要乘以页面的实际宽高：

# 假设页面宽 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 字段。

{
  "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 版本迁移指南
`objects`	array	单元格内嵌对象列表（需开启 `include_inline_objects`）
`char_details`	array	字符级详情（需开启 `include_char_details`）

当请求参数 element_merge_mode 为 merged 时，合并后的单元格还会返回 source_regions、role、header_cell_ids、text_source_ranges 等跨页来源字段，详见跨页表格合并。

跨页表格合并（merged 模式）

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

element_merge_mode 的取值与配置方式，详见解析配置详解。

两种模式对比

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

[
  {
    "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。

{
  "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": ["..."]
  }
}

table_structure_status 为 available 时，Table 必定带 table_structure（合并后的单元格结构，示例中的 cells 已省略，详见单元格新增字段）；为 disabled 或 unavailable 时则不返回 table_structure。

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

表级新增字段（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 归一化，否则区间会错位

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

Cell 关闭时（include_table_structure=false）

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

{
  "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 字段。

{
  "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 字段，提供字符级别的坐标和识别置信度。

{
  "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 字段，标识文本中的公式、手写体、复选框等行内元素。

{
  "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 能力时，返回文档的层级目录结构：

{
  "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 能力时，返回每一页的元信息：

{
  "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 时，响应的 data 中会返回 exports 数组，包含各导出任务的状态与文件信息。

{
  "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` 互斥）

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

下载导出文件

使用 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 为文件二进制内容）。

下载约束

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

处理摘要（summary）

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

{
  "summary": {
    "duration_ms": 812
  }
}

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

错误响应

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

{
  "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	服务器内部错误

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

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

错误码	说明	排查方向
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 凭证下载

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

GUI 识别引擎特别说明

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

GUI 引擎仅支持图片格式输入（JPEG、PNG、GIF、WebP），文件大小不超过 10MB，不支持 PDF 等文档格式。配置方法详见解析配置 - force_engine。

基本结构

{
  "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	元素的语义描述

快速入门

从零开始完成第一次文档解析

解析配置详解

深入了解所有输入参数配置，自定义解析行为

API 参考

完整的请求参数与响应 Schema

Python SDK

SDK 高级用法与最佳实践

​响应总览

​顶层字段

​data 字段

​metadata（文件元信息）

​elements（文档元素）

​基本结构

​基础字段

​元素类型

​metadata 字段

​坐标系统

​表格结构（table_structure）

​单元格字段

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

​两种模式对比

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

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

​Cell 关闭时（include_table_structure=false）

​图片数据（image_data）

​字符级详情（char_details）

​行内对象（objects）

​目录树（title_tree）

​页面信息（pages）

​格式转换结果（exports）

​下载导出文件

​处理摘要（summary）

​错误响应

​常见错误码

​GUI 识别引擎特别说明

​基本结构

​基础字段

​UI 元素类型（type）

​metadata 字段

​相关链接

快速入门

解析配置详解

API 参考

Python SDK

响应总览

顶层字段

data 字段

metadata（文件元信息）

elements（文档元素）

基本结构

基础字段

元素类型

metadata 字段

坐标系统

表格结构（table_structure）

单元格字段

跨页表格合并（merged 模式）

两种模式对比

表级新增字段（merged 模式）

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

Cell 关闭时（include_table_structure=false）

图片数据（image_data）

字符级详情（char_details）

行内对象（objects）

目录树（title_tree）

页面信息（pages）

格式转换结果（exports）

下载导出文件

处理摘要（summary）

错误响应

常见错误码

GUI 识别引擎特别说明

基本结构

基础字段

UI 元素类型（type）

metadata 字段

相关链接