返回结构详解

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

基本结构

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

元素类型

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

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_data`	object	图片数据（当 `content_type` 为 `image` 时，需开启 `include_image_data`）
`objects`	array	单元格内嵌对象列表（需开启 `include_inline_objects`）
`char_details`	array	字符级详情（需开启 `include_char_details`）

图片数据（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"],
      "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）

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

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

常见错误码

错误码	说明
40101	`x-ti-app-id` 无效
40102	`x-ti-secret-code` 无效
40103	IP 不在白名单内
40003	余额不足
40004	参数错误
40301	不支持的文件类型
40302	文件超过大小限制（500MB）
40305	识别文件未上传
40422	文件损坏，无法解析
40423	PDF 密码错误
40424	页数设置超出文件范围
40425	文件格式不支持
40427	DPI 参数不在支持列表中
40428	Word 和 PPT 转 PDF 失败或者超时
40429	不支持的引擎
50207	部分页面解析失败
40400	无效的请求链接
30203	基础服务故障，请稍后重试
500	服务器内部错误

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

快速入门

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

解析配置详解

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

API 参考

完整的请求参数与响应 Schema

Python SDK

SDK 高级用法与最佳实践

产品概览

文档解析

文档解析新版

文档抽取

FAQ

响应总览

顶层字段

data 字段

metadata（文件元信息）

elements（文档元素）

基本结构

基础字段

元素类型

metadata 字段

坐标系统

表格结构（table_structure）

单元格字段

图片数据（image_data）

字符级详情（char_details）

行内对象（objects）

目录树（title_tree）

页面信息（pages）

处理摘要（summary）

错误响应

常见错误码

相关链接

快速入门

解析配置详解

API 参考

Python SDK

产品概览

文档解析

文档解析新版

文档抽取

FAQ

​响应总览

​顶层字段

​data 字段

​metadata（文件元信息）

​elements（文档元素）

​基本结构

​基础字段

​元素类型

​metadata 字段

​坐标系统

​表格结构（table_structure）

​单元格字段

​图片数据（image_data）

​字符级详情（char_details）

​行内对象（objects）

​目录树（title_tree）

​页面信息（pages）

​处理摘要（summary）

​错误响应

​常见错误码

​相关链接

快速入门

解析配置详解

API 参考

Python SDK

响应总览

顶层字段

data 字段

metadata（文件元信息）

elements（文档元素）

基本结构

基础字段

元素类型

metadata 字段

坐标系统

表格结构（table_structure）

单元格字段

图片数据（image_data）

字符级详情（char_details）

行内对象（objects）

目录树（title_tree）

页面信息（pages）

处理摘要（summary）

错误响应

常见错误码

相关链接