查询解析结果 — 返回字段说明

接口：GET /openapi/doc-parser/tasks/{task_id}

只能查询当前调用方自己的任务。解析结果在成功时原样返回，并额外带上 status。

响应总览

所有响应（成功 / 失败 / 处理中）统一包裹在顶层信封中：

{
    "code": 0,
    "msg": "success",
    "data": { ... }
}

字段	类型	说明
`code`	int	`0` 表示成功或任务仍在处理；非 0 表示失败，应停止轮询。取值见下方「错误响应」
`msg`	string	成功或处理中为 `"success"`，失败时为错误说明
`data`	object / null	处理中或成功时为结果对象；失败时为空

三种形态：

场景	code	data
处理中（排队 / 执行中）	`0`	`{ "status": "pending", "message": "task pending" / "task running" }`，继续轮询
解析成功	`0`	`status` 为 `completed`，并包含 `version` / `pages` / `blocks` / `md`
失败	非 0	空。按 `code` 与 `msg` 处理，停止轮询

注意: 成功与失败响应的 HTTP 状态码恒为 200，调用方必须以信封中的 code 判断结果，不能依赖 HTTP 状态码。处理中也是 code = 0，用 data.status 区分是否还要轮询。

处理中示例：

{
    "code": 0,
    "msg": "success",
    "data": {
        "status": "pending",
        "message": "task running"
    }
}

错误响应（报错异常与错误码）

失败时没有 data。code 为错误码，msg 为说明。

{
    "code": 40013,
    "msg": "The provided PDF file is encrypted."
}

错误码一览

平台错误：

code	msg	触发场景
`3010`	`数据不存在！`	任务不存在，或不属于当前调用方
`6032`	`无效的appid或者access-token`	`appid` 无效
`6033`	`无效的签名`	缺少 `sign`
`6034`	`无效的nonce`	`nonce` 无效，长度必须为 16
`6035`	`签名已过期`	签名过期
`6036`	`验签失败`	签名不正确
`6040`	`未开通该功能权益，请联系管理员配置` / `使用额度不足！`	未开通 `doc-parse`，或额度不足（创建任务时）
`6044`	`权益已过期！`	权益已过期（创建任务时）
`6061`	`通用能力接口异常！`	下游无响应，或下游令牌校验失败。查询时若任务仍在处理，可稍后重试

解析失败（code 与 msg 透传下游）：

code	msg	触发场景
`40002`	`Failed to download file: <异常类型>` 或响应文本	`file_url` 下载失败（网络错误 / 超时），或 HTTP 状态非 200
`40010`	`The provided URL does not point to a PDF file`	下载的内容不是 PDF 文件
`40013`	`The provided PDF file is encrypted.`	PDF 已加密，无法解析
`40011`	`The provided document is invalidated.`	文档数据为空或 PDF 加载失败
`41301`	`The document exceeds the maximum number of pages allowed: <maxPages>`	文档页数超过 `max_pages` 限制
`40200`	`当前服务License已过期，请联系商务完成续期后恢复使用`	License 授权已过期
`40201`	`根目录下未找到授权文件，机器码: <machine_id>`	下游未找到授权文件且无法在线激活
`40202`	`非授权用户（机器码不匹配）` / `授权检查失败：<原因>` / `联网激活失败：<code>, <msg>`	机器码不匹配、授权文件损坏或在线激活失败
`404`	`task not found: <taskId>`	下游任务不存在或已失效
`422`	`Request validation failed`	下游参数校验失败
`500`	异常文本	下游未捕获的内部异常

data 字段结构（成功）

code = 0 且 data.status = completed 时：

字段	类型	说明
`status`	string	固定为 `"completed"`
`version`	string	输出格式版本号，当前为 `"v1.0"`
`pages`	`Page[]`	逐页解析结果，按阅读顺序排列
`blocks`	`MergedBlock[]`	跨页合并后的逻辑块，按阅读顺序排列
`md`	string	整个文档的 Markdown 文本（不含 header / footer / seal / header_image / footer_image 块）

处理中时 data 只有：

字段	类型	说明
`status`	string	固定为 `"pending"`
`message`	string	`task pending` 或 `task running`，都表示未完成，继续轮询

Page 对象

字段	类型	说明
`pageIndex`	int	页码，从 0 开始
`imageUrl`	string	经过方向矫正后的页面图片 URL（或 Base64 PNG）
`imageWidth`	int	页面图片宽度（像素）
`imageHeight`	int	页面图片高度（像素）
`blocks`	`Block[]`	当前页面上的所有原始块，按阅读顺序排列

Block 对象

Block 表示页面上识别出的一个内容区域。不同块类型有公共字段和专有字段。

公共字段（所有 Block 类型均有）

字段	类型	说明
`id`	string	文档内唯一标识
`blockType`	string	块类型，取值见下表
`bbox`	`[float, float, float, float]`	边界框 `[x1, y1, x2, y2]`，坐标为 float

blockType 枚举

值	说明	额外字段
`"title"`	标题	text, lines
`"text"`	正文段落	text, lines
`"header"`	页眉	text, lines
`"footer"`	页脚	text, lines
`"reference"`	参考文献	text, lines
`"catalog"`	目录	text, lines
`"table"`	表格	title, cells
`"image"`	图片	caption, text, lines
`"formula"`	公式	latex, text, lines
`"seal"`	印章	无
`"header_image"`	页眉图片	无
`"footer_image"`	页脚图片	无

文本类块专有字段（title / text / header / footer / reference / catalog）

字段	类型	说明
`text`	string	块的所有文本拼接
`lines`	`Line[]`	构成文本的行数组

Table 块专有字段

字段	类型	说明
`title`	string	表格标题（位于表格上方）
`cells`	`Cell[]`	表格单元格数组

Image 块专有字段

字段	类型	说明
`caption`	string	图片说明文字
`text`	string	图片 OCR 识别文字
`lines`	`Line[]`	OCR 行数组

Formula 块专有字段

字段	类型	说明
`latex`	string	公式 LaTeX 表示
`text`	string	公式纯文本表示
`lines`	`Line[]`	OCR 行数组

seal / header_image / footer_image

仅有公共字段（id、blockType、bbox），无额外字段。

Line 对象

字段	类型	说明
`id`	string	行唯一标识
`bbox`	`[int, int, int, int]`	行边界框 `[x1, y1, x2, y2]`，坐标强制为 int
`score`	int	OCR 置信度（0–100）
`chars`	`Char[]`	字符数组

Char 对象

字段	类型	说明
`c`	string	单个字符
`b`	`[int, int, int, int]`	字符边界框 `[x1, y1, x2, y2]`，坐标为 int

Cell 对象（表格单元格）

字段	类型	说明
`id`	string	单元格唯一标识
`bbox`	`[float, float, float, float]`	单元格边界框 `[x1, y1, x2, y2]`
`text`	string	单元格文本内容
`lines`	`Line[]`	单元格内的行数组

MergedBlock 对象（跨页合并后的逻辑块）

data.blocks[] 中的每个元素是将同一逻辑块跨页拼接后的结果。例如，一个跨页表格在此处为一个 MergedBlock，而非两个。

公共字段（所有 MergedBlock 类型均有）

字段	类型	说明
`blockType`	string	块类型，同 Block.blockType
`pageRange`	`[int, int]`	`[起始页码, 结束页码]`，页码从 0 开始
`sourceBlockIds`	`string[]`	合并前原始 Block 的 id 列表

文本类 MergedBlock（title / text / header / footer / reference / catalog）

字段	类型	说明
`text`	string	跨页合并后的完整文本
`sourceLineIds`	`string[]`	合并前原始 Line 的 id 列表

Formula MergedBlock

字段	类型	说明
`text`	string	公式文本
`sourceLineIds`	`string[]`	合并前原始 Line 的 id 列表

Table MergedBlock

字段	类型	说明
`title`	string	表格标题
`nRows`	int	逻辑总行数（合并后）
`nCols`	int	逻辑总列数（合并后）
`cells`	`MergedCell[]`	逻辑单元格数组

Image MergedBlock

字段	类型	说明
`text`	string	合并后的图片 OCR 文字
`caption`	string	合并后的图片说明
`sourceLineIds`	`string[]`	合并前原始 Line 的 id 列表

seal / header_image / footer_image MergedBlock

仅有公共字段（blockType、pageRange、sourceBlockIds）。

MergedCell 对象（MergedBlock 中的单元格）

字段	类型	说明
`row`	int	网格行索引（从 0 开始）
`col`	int	网格列索引（从 0 开始）
`rowspan`	int	行跨度（>= 1）
`colspan`	int	列跨度（>= 1）
`sourceCellIds`	`string[]`	合并前原始 Cell 的 id 列表

注意: MergedCell 不包含 text 字段。如需获取单元格文本，需通过 sourceCellIds 回查对应 Page 中 Cell 的 text 内容。

完整示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "status": "completed",
        "version": "v1.0",
        "pages": [
            {
                "pageIndex": 0,
                "imageUrl": "https://s3.example.com/pages/page_0.png",
                "imageWidth": 1200,
                "imageHeight": 1600,
                "blocks": [
                    {
                        "id": "block_001",
                        "blockType": "title",
                        "bbox": [100.0, 50.0, 700.0, 90.0],
                        "text": "第一章 概述",
                        "lines": [
                            {
                                "id": "line_001",
                                "bbox": [100, 50, 700, 90],
                                "score": 99,
                                "chars": [
                                    {"c": "第", "b": [100, 50, 120, 90]},
                                    {"c": "一", "b": [120, 50, 140, 90]}
                                ]
                            }
                        ]
                    },
                    {
                        "id": "block_002",
                        "blockType": "text",
                        "bbox": [80.0, 120.0, 720.0, 200.0],
                        "text": "这是正文内容示例。",
                        "lines": [
                            {
                                "id": "line_002",
                                "bbox": [80, 120, 720, 160],
                                "score": 98,
                                "chars": [
                                    {"c": "这", "b": [80, 120, 100, 160]}
                                ]
                            }
                        ]
                    },
                    {
                        "id": "block_003",
                        "blockType": "table",
                        "bbox": [80.0, 220.0, 720.0, 500.0],
                        "title": "表1 示例数据",
                        "cells": [
                            {
                                "id": "cell_001",
                                "bbox": [80.0, 220.0, 200.0, 260.0],
                                "text": "姓名",
                                "lines": []
                            },
                            {
                                "id": "cell_002",
                                "bbox": [200.0, 220.0, 400.0, 260.0],
                                "text": "年龄",
                                "lines": []
                            }
                        ]
                    },
                    {
                        "id": "block_004",
                        "blockType": "image",
                        "bbox": [200.0, 520.0, 600.0, 800.0],
                        "caption": "图1 架构图",
                        "text": "",
                        "lines": []
                    },
                    {
                        "id": "block_005",
                        "blockType": "formula",
                        "bbox": [100.0, 820.0, 700.0, 880.0],
                        "latex": "E = mc^2",
                        "text": "E = mc^2",
                        "lines": []
                    }
                ]
            }
        ],
        "blocks": [
            {
                "blockType": "title",
                "pageRange": [0, 0],
                "sourceBlockIds": ["block_001"],
                "text": "第一章 概述",
                "sourceLineIds": ["line_001"]
            },
            {
                "blockType": "text",
                "pageRange": [0, 0],
                "sourceBlockIds": ["block_002"],
                "text": "这是正文内容示例。",
                "sourceLineIds": ["line_002"]
            },
            {
                "blockType": "table",
                "pageRange": [0, 0],
                "sourceBlockIds": ["block_003"],
                "title": "表1 示例数据",
                "nRows": 2,
                "nCols": 2,
                "cells": [
                    {
                        "row": 0,
                        "col": 0,
                        "rowspan": 1,
                        "colspan": 1,
                        "sourceCellIds": ["cell_001"]
                    },
                    {
                        "row": 0,
                        "col": 1,
                        "rowspan": 1,
                        "colspan": 1,
                        "sourceCellIds": ["cell_002"]
                    }
                ]
            },
            {
                "blockType": "image",
                "pageRange": [0, 0],
                "sourceBlockIds": ["block_004"],
                "text": "",
                "caption": "图1 架构图",
                "sourceLineIds": []
            },
            {
                "blockType": "formula",
                "pageRange": [0, 0],
                "sourceBlockIds": ["block_005"],
                "text": "E = mc^2",
                "sourceLineIds": []
            }
        ],
        "md": "## 第一章 概述\n\n这是正文内容示例。\n\n<table>\n  <caption>表1 示例数据</caption>\n  <tr><td>姓名</td><td>年龄</td></tr>\n</table>\n\n![图1 架构图]()\n\n$$\nE = mc^2\n$$\n"
    }
}

关键注意事项

pages vs blocks 两个层级: pages[].blocks[] 是逐页的原始块（保留字符级别细节）。顶层 blocks[] 是跨页合并后的逻辑块（通过 sourceBlockIds / sourceLineIds / sourceCellIds 回链到原始数据）。

MergedCell 不含 text: 跨页合并后的单元格不直接包含文字内容。如果需要单元格文本，通过 sourceCellIds 去 pages[].blocks[].cells[] 中查找对应 Cell 的 text 字段。

Line.bbox 为 int: Line 和 Char 的边界框坐标强制转为 int，Block 和 Cell 的 bbox 保留 float。

md 内容过滤: Markdown 输出会自动过滤掉 header、footer、seal、header_image、footer_image 类块，且不包含字符级别的细节信息。

用 status 判断是否轮询: code = 0 且 data.status = pending 时继续轮询；status = completed 时取结果；code 非 0 时停止。

application/json

HTTP 恒为 200，以 body.code 与 data.status 判断

Bodyapplication/json

示例

未完成解析成功任务不存在解析失败

{
    "code": 0,
    "msg": "success",
    "data": {
        "status": "pending",
        "message": "task running"
    }
}

查询解析结果

查询解析结果 — 返回字段说明

响应总览

错误响应（报错异常与错误码）

错误码一览

data 字段结构（成功）

Page 对象

Block 对象

公共字段（所有 Block 类型均有）

blockType 枚举

文本类块专有字段（title / text / header / footer / reference / catalog）

Table 块专有字段

Image 块专有字段

Formula 块专有字段

seal / header_image / footer_image

Line 对象

Char 对象

Cell 对象（表格单元格）

MergedBlock 对象（跨页合并后的逻辑块）

公共字段（所有 MergedBlock 类型均有）

文本类 MergedBlock（title / text / header / footer / reference / catalog）

Formula MergedBlock

Table MergedBlock

Image MergedBlock

seal / header_image / footer_image MergedBlock

MergedCell 对象（MergedBlock 中的单元格）

完整示例

关键注意事项

请求参数

请求示例代码

返回响应

查询解析结果

查询解析结果 — 返回字段说明#

响应总览#

错误响应（报错异常与错误码）#

错误码一览#

data 字段结构（成功）#

Page 对象#

Block 对象#

公共字段（所有 Block 类型均有）#

blockType 枚举#

文本类块专有字段（title / text / header / footer / reference / catalog）#

Table 块专有字段#

Image 块专有字段#

Formula 块专有字段#

seal / header_image / footer_image#

Line 对象#

Char 对象#

Cell 对象（表格单元格）#

MergedBlock 对象（跨页合并后的逻辑块）#

公共字段（所有 MergedBlock 类型均有）#

文本类 MergedBlock（title / text / header / footer / reference / catalog）#

Formula MergedBlock#

Table MergedBlock#

Image MergedBlock#

seal / header_image / footer_image MergedBlock#

MergedCell 对象（MergedBlock 中的单元格）#

完整示例#

关键注意事项#

请求参数

请求示例代码

返回响应

查询解析结果 — 返回字段说明

响应总览

错误响应（报错异常与错误码）

错误码一览

data 字段结构（成功）

Page 对象

Block 对象

公共字段（所有 Block 类型均有）

blockType 枚举

文本类块专有字段（title / text / header / footer / reference / catalog）

Table 块专有字段

Image 块专有字段

Formula 块专有字段

seal / header_image / footer_image

Line 对象

Char 对象

Cell 对象（表格单元格）

MergedBlock 对象（跨页合并后的逻辑块）

公共字段（所有 MergedBlock 类型均有）

文本类 MergedBlock（title / text / header / footer / reference / catalog）

Formula MergedBlock

Table MergedBlock

Image MergedBlock

seal / header_image / footer_image MergedBlock

MergedCell 对象（MergedBlock 中的单元格）

完整示例

关键注意事项