返回结构详解

文档解析 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

常见错误码

错误码	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 联系技术支持排查问题。

快速入门

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

解析配置详解

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

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）

错误响应

常见错误码

相关链接