腾讯云智能体开发平台 ADP 文档解析协议

说明：
ADP 文档解析协议主要用于澄清 ADP 定义的文档解析协议，指导用户进行服务封装。如需了解文档解析服务在 ADP 的接入全流程，您可访问 ADP文档解析服务接入指引。
版本信息
版本号：v1.0
更新日期：2025-12-23
协议：HTTPS
请求方法：POST
数据格式：JSON
字符编码：UTF-8
鉴权方式
Bearer Token 认证
所有 API 请求都需要在 HTTP Header 中携带 Bearer Token 进行身份认证。
Header 格式：
Authorization: Bearer {your_access_token}
示例：
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
接口列表
1. 提交文档解析任务
接口描述
提交一个文档解析任务，支持 PDF、Word、Excel、PPT 等多种文档格式。任务提交后会返回 TaskId，用于后续查询解析结果。
接口地址
POST https://api.example.com/api/v1/document/parse/submit
请求头（Headers）
参数名
类型
必填
说明
Authorization
string
是
Bearer Token 认证
Content-Type
string
是
application/json
请求参数（Request Body）
参数名
类型
必填
说明
示例
FileType
string
是
文件类型，支持：PDF、DOCX、DOC、XLSX、XLS、PPTX、PPT、TXT、MD、HTML
"PDF"
FileName
string
是
文件名称，包含扩展名
"example.pdf"
FileUrl
string
是
文件下载地址，必须是可访问的 HTTPS 链接，支持带签名的临时链接（有效期建议 ≥ 1小时）
文件 url
请求示例
{
  "FileType": "PDF",
  "FileName": "example.pdf",
  "FileUrl": "https://example.cos.ap-guangzhou.myqcloud.com/public/example/example.pdf"
}
响应参数（Response）
参数名
类型
说明
Response
object
响应对象
Response.RequestId
string
请求唯一标识，用于问题排查
Response.TaskId
string
任务唯一标识，用于查询解析结果
响应示例
成功响应（200 OK）：
{
  "Response": {
    "RequestId": "5e148c27-9c21-43cd-992c-799117bb4216",
    "TaskId": "236e51fd-827b-41cb-b303-56003a817ce5"
  }
}
错误响应：
{
  "Response": {
    "Error": {
      "Code": "InvalidParameter",
      "Message": "FileUrl is required"
    },
    "RequestId": "5e148c27-9c21-43cd-992c-799117bb4216"
  }
}
错误码说明
错误码
HTTP 状态码
说明
InvalidParameter
400
请求参数错误
InvalidFileUrl
400
文件 URL 无效或无法访问
UnsupportedFileType
400
不支持的文件类型
Unauthorized
401
未授权，Token 缺失
Forbidden
403
Token 无效或已过期
FileTooLarge
413
文件大小超过限制
TooManyRequests
429
请求频率超限
InternalError
500
服务内部错误
2. 查询文档解析结果
接口描述
根据 TaskId 查询文档解析任务的状态和结果。解析完成后会返回结果文件的下载地址。
接口地址
POST https://api.example.com/api/v1/document/parse/query
请求头（Headers）
参数名
类型
必填
说明
Authorization
string
是
Bearer Token 认证
Content-Type
string
是
application/json
请求参数（Request Body）
参数名
类型
必填
说明
示例
TaskId
string
是
任务唯一标识，由提交接口返回
"236e51fd-827b-41cb-b303-56003a817ce5"
请求示例
{
  "TaskId": "236e51fd-827b-41cb-b303-56003a817ce5"
}
响应参数（Response）
参数名
类型
说明
Response
object
响应对象
Response.RequestId
string
请求唯一标识
Response.Status
string
任务状态：
Pending（等待中）
Processing（处理中）
Success（成功）
Failed（失败）
Response.DocumentRecognizeResultUrl
string
解析结果文件下载地址（ZIP 格式），仅在 Status 为 Success 时返回
Response.Progress
integer
任务进度（0-100），仅在 Status 为 Processing 时返回
Response.ErrorCode
string
错误码，仅在 Status 为 Failed 时返回
Response.ErrorMessage
string
错误信息，仅在 Status 为 Failed 时返回
响应示例
成功响应 - 任务完成（200 OK）：
{
  "Response": {
    "RequestId": "ffe23ed8-2b64-4835-aedc-ca9a5b5a7384",
    "Status": "Success",
    "DocumentRecognizeResultUrl": "https://example.cos.ap-guangzhou.myqcloud.com/public/example/example.zip"
  }
}
成功响应 - 任务处理中（200 OK）：
{
  "Response": {
    "RequestId": "ffe23ed8-2b64-4835-aedc-ca9a5b5a7384",
    "Status": "Processing",
    "Progress": 65
  }
}
成功响应 - 任务等待中（200 OK）：
{
  "Response": {
    "RequestId": "ffe23ed8-2b64-4835-aedc-ca9a5b5a7384",
    "Status": "Pending"
  }
}
成功响应 - 任务失败（200 OK）：
{
  "Response": {
    "RequestId": "ffe23ed8-2b64-4835-aedc-ca9a5b5a7384",
    "Status": "Failed",
    "ErrorCode": "ParseError",
    "ErrorMessage": "文档格式损坏，无法解析"
  }
}
错误响应 - 任务不存在（404 Not Found）：
{
  "Response": {
    "Error": {
      "Code": "TaskNotFound",
      "Message": "Task not found"
    },
    "RequestId": "ffe23ed8-2b64-4835-aedc-ca9a5b5a7384"
  }
}
任务状态说明
状态
说明
建议操作
Pending
任务已提交，等待处理
继续轮询查询
Processing
任务处理中
继续轮询查询
Success
任务成功完成
下载结果文件
Failed
任务失败
查看错误信息，重新提交
错误码说明
错误码
HTTP 状态码
说明
InvalidParameter
400
请求参数错误
TaskNotFound
404
任务不存在
Unauthorized
401
未授权，Token 缺失
Forbidden
403
Token 无效或已过期
InternalError
500
服务内部错误
3. 同步解析接口
接口描述
提交一个文档解析任务，支持 PDF、Word、Excel、PPT 等多种文档格式。任务提交后会返回 TaskId，用于后续查询解析结果。
接口地址
POST https://api.example.com/api/v1/document/parse/sync_parse
请求头（Headers）
参数名
类型
必填
说明
Authorization
string
是
Bearer Token 认证
Content-Type
string
是
application/json
请求参数（Request Body）
参数名
类型
必填
说明
示例
FileType
string
是
文件类型，支持：PDF、DOCX、DOC、XLSX、XLS、PPTX、PPT、TXT、MD、HTML
"PDF"
FileName
string
是
文件名称，包含扩展名
"example.pdf"
FileUrl
string
是
文件下载地址，必须是可访问的 HTTPS 链接，支持带签名的临时链接（有效期建议 ≥ 1小时）
文件 url
请求示例
{
  "FileType": "PDF",
  "FileName": "example.pdf",
  "FileUrl": "https://example.cos.ap-guangzhou.myqcloud.com/public/example/example.pdf"
}
响应参数（Response）
参数名
类型
说明
Response
object
响应对象
Response.RequestId
string
请求唯一标识
Response.Status
string
任务状态：
Pending（等待中）
Processing（处理中）
Success（成功）
Failed（失败）
Response.DocumentRecognizeResultUrl
string
解析结果文件下载地址（ZIP 格式），仅在 Status 为 Success 时返回
Response.Progress
integer
任务进度（0-100），仅在 Status 为 Processing 时返回
Response.ErrorCode
string
错误码，仅在 Status 为 Failed 时返回
Response.ErrorMessage
string
错误信息，仅在 Status 为 Failed 时返回
响应示例
成功响应 - 任务完成（200 OK）：
{
  "Response": {
    "RequestId": "ffe23ed8-2b64-4835-aedc-ca9a5b5a7384",
    "Status": "Success",
    "DocumentRecognizeResultUrl": "https://example.cos.ap-guangzhou.myqcloud.com/public/example/example.zip"
  }
}
错误响应 - 任务失败（200 OK）：
{
  "Response": {
    "RequestId": "ffe23ed8-2b64-4835-aedc-ca9a5b5a7384",
    "Status": "Failed",
    "ErrorCode": "ParseError",
    "ErrorMessage": "文档格式损坏，无法解析"
  }
}
错误响应 - 参数错误（400 Bad Request）：
{
  "Response": {
    "Error": {
      "Code": "InvalidParameter",
      "Message": "FileUrl is required"
    },
    "RequestId": "ffe23ed8-2b64-4835-aedc-ca9a5b5a7384"
  }
}
错误码说明
错误码
HTTP 状态码
说明
InvalidParameter
400
请求参数错误
InvalidFileUrl
400
文件 URL 无效或无法访问
UnsupportedFileType
400
不支持的文件类型
Unauthorized
401
未授权，Token 缺失
Forbidden
403
Token 无效或已过期
FileTooLarge
413
文件大小超过限制
TooManyRequests
429
请求频率超限
RequestTimeout
408
请求超时（解析时间过长）
InternalError
500
服务内部错误
解析结果文件说明
结果文件格式
解析完成后，DocumentRecognizeResultUrl 返回的是一个 ZIP 压缩包的下载地址，包含以下内容：
76aef68b-c444-41d2-829a-d513fa35e42b.zip                     # DocumentRecognizeResultUrl 下载得到的zip文件
├── 76aef68b-c444-41d2-829a-d513fa35e42b/                    # 内层目录（以任务ID命名）
│   ├── 76aef68b-c444-41d2-829a-d513fa35e42b_parse_page0.json  # 第1页的解析结果
│   ├── 76aef68b-c444-41d2-829a-d513fa35e42b_parse_page1.json  # 第2页的解析结果
│   ├── ...                                                  # 更多页面的解析结果
│   └── images/                                              # 提取的图片目录
│       ├── 76c7b6051d432f6527bd91a02321d126-image.png     # 图片文件（UUID命名）
│       └── ...
解析结果文件结构说明
每个页面的解析结果保存在独立的 JSON 文件中（*_parse_page{N}.json），包含该页面的完整识别信息。
解析页面结构（Page Object）
字段名
类型
说明
PageNumber
integer
页码，从 1 开始
Angle
integer
页面旋转角度（度）
RotatedAngle
integer
已旋转的角度（度）
Height
integer
页面高度（像素）
Width
integer
页面宽度（像素）
OriginHeight
integer
原始页面高度（像素）
OriginWidth
integer
原始页面宽度（像素）
Elements
array
页面元素列表，详见下方说明
元素结构（Element Object）
字段名
类型
说明
Index
integer
元素在页面中的索引，从 0 开始
Type
string
元素类型：title（标题）、text（文本）、figure（图表）、table（表格）、figure_text（图表中的文本）
Text
string
元素的文本内容
Level
integer
元素层级，0 表示顶层元素，1 表示嵌套元素
Polygon
object
元素的位置坐标（四边形），详见下方说明
InsetImageName
string
内嵌图片名称（如果有）
Elements
array
嵌套的子元素列表（递归结构）
ImagePath
string
图片文件路径（相对于 ZIP 根目录）
坐标结构（Polygon Object）
字段名
类型
说明
LeftTop
object
左上角坐标 {"X": int, "Y": int}
RightTop
object
右上角坐标 {"X": int, "Y": int}
LeftBottom
object
左下角坐标 {"X": int, "Y": int}
RightBottom
object
右下角坐标 {"X": int, "Y": int}
坐标系说明：
原点 (0, 0) 位于页面左上角。
X 轴向右递增。
Y 轴向下递增。
元素类型说明
Type
说明
特点
title
标题
通常是文档的章节标题
text
普通文本
段落、正文内容
figure
图表
包含图片、图表等可视化内容，可能包含嵌套的 figure_text
figure_text
图表中的文本
图表内部识别出的文本内容
table
表格
结构化的表格数据
解析结果示例
示例 1：包含标题和图表的页面
{
  "PageNumber": 1,
  "Angle": 0,
  "RotatedAngle": 0,
  "Height": 286,
  "Width": 736,
  "OriginHeight": 286,
  "OriginWidth": 736,
  "Elements": [
    {
      "Index": 0,
      "Type": "title",
      "Text": "# 数据规模",
      "Level": 0,
      "Polygon": {
        "LeftTop": {"X": 3, "Y": 98},
        "RightTop": {"X": 25, "Y": 98},
        "LeftBottom": {"X": 3, "Y": 169},
        "RightBottom": {"X": 25, "Y": 169}
      },
      "InsetImageName": "",
      "Elements": null,
      "ImagePath": ""
    },
    {
      "Index": 1,
      "Type": "figure",
      "Text": "",
      "Level": 0,
      "Polygon": {
        "LeftTop": {"X": 41, "Y": 4},
        "RightTop": {"X": 733, "Y": 4},
        "LeftBottom": {"X": 41, "Y": 286},
        "RightBottom": {"X": 733, "Y": 286}
      },
      "InsetImageName": "",
      "Elements": [
        {
          "Index": 0,
          "Type": "figure_text",
          "Text": "10 000 000\\n1 000 000\\n100 000\\n10 000\\n1 000",
          "Level": 1,
          "Polygon": {
            "LeftTop": {"X": 41, "Y": 4},
            "RightTop": {"X": 733, "Y": 4},
            "LeftBottom": {"X": 41, "Y": 286},
            "RightBottom": {"X": 733, "Y": 286}
          },
          "InsetImageName": "",
          "Elements": null,
          "ImagePath": ""
        }
      ],
      "ImagePath": "images/76c7b6051d432f6527bd91a02321d126-image.png"
    }
  ]
}
示例 2：包含文本和表格的页面
{
  "PageNumber": 2,
  "Angle": 0,
  "RotatedAngle": 0,
  "Height": 842,
  "Width": 595,
  "OriginHeight": 842,
  "OriginWidth": 595,
  "Elements": [
    {
      "Index": 0,
      "Type": "text",
      "Text": "这是一段普通的文本内容，用于说明文档的主要信息。",
      "Level": 0,
      "Polygon": {
        "LeftTop": {"X": 50, "Y": 100},
        "RightTop": {"X": 545, "Y": 100},
        "LeftBottom": {"X": 50, "Y": 130},
        "RightBottom": {"X": 545, "Y": 130}
      },
      "InsetImageName": "",
      "Elements": null,
      "ImagePath": ""
    },
    {
      "Index": 1,
      "Type": "table",
      "Text": "姓名\\t年龄\\t职位\\n张三\\t28\\t工程师\\n李四\\t32\\t经理",
      "Level": 0,
      "Polygon": {
        "LeftTop": {"X": 50, "Y": 200},
        "RightTop": {"X": 545, "Y": 200},
        "LeftBottom": {"X": 50, "Y": 350},
        "RightBottom": {"X": 545, "Y": 350}
      },
      "InsetImageName": "",
      "Elements": null,
      "ImagePath": ""
    }
  ]
}
接口调用代码示例
Python 示例
import requests
import time
import json
﻿
# 配置
API_BASE_URL = "https://api.example.com"
BEARER_TOKEN = "your_access_token"
﻿
headers = {
    "Authorization": f"Bearer {BEARER_TOKEN}",
    "Content-Type": "application/json"
}
﻿
# 1. 提交解析任务
def submit_parse_task(file_url, file_name, file_type):
    url = f"{API_BASE_URL}/api/v1/document/parse/submit"
    payload = {
        "FileType": file_type,
        "FileName": file_name,
        "FileUrl": file_url
    }
﻿
    response = requests.post(url, headers=headers, json=payload)
    response.raise_for_status()
﻿
    result = response.json()
    return result["Response"]["TaskId"]
﻿
# 2. 查询解析结果
def query_parse_result(task_id, max_retries=60, interval=5):
    url = f"{API_BASE_URL}/api/v1/document/parse/query"
    payload = {"TaskId": task_id}
﻿
    for i in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)
        response.raise_for_status()
﻿
        result = response.json()["Response"]
        status = result["Status"]
﻿
        print(f"[{i+1}/{max_retries}] Task status: {status}")
﻿
        if status == "Success":
            return result["DocumentRecognizeResultUrl"]
        elif status == "Failed":
            raise Exception(f"Parse failed: {result.get('ErrorMessage')}")
﻿
        time.sleep(interval)
﻿
    raise Exception("Query timeout")
﻿
# 3. 使用示例
try:
    # 提交任务
    task_id = submit_parse_task(
        file_url="https://example.com/document.pdf",
        file_name="document.pdf",
        file_type="PDF"
    )
    print(f"Task submitted: {task_id}")
﻿
    # 查询结果
    result_url = query_parse_result(task_id)
    print(f"Parse completed: {result_url}")
﻿
    # 下载结果
    # download_and_extract(result_url)
﻿
except Exception as e:
    print(f"Error: {e}")
Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: Python 3.11.1
Python 同步接口示例
import requests
import json
﻿
# 配置
API_BASE_URL = "https://api.example.com"
BEARER_TOKEN = "your_access_token"
﻿
headers = {
    "Authorization": f"Bearer {BEARER_TOKEN}",
    "Content-Type": "application/json"
}
﻿
# 同步解析（一次请求获得结果）
def sync_parse_document(file_url, file_name, file_type):
    url = f"{API_BASE_URL}/api/v1/document/parse/sync_parse"
    payload = {
        "FileType": file_type,
        "FileName": file_name,
        "FileUrl": file_url
    }
﻿
    # 设置较长的超时时间（建议 5 分钟）
    response = requests.post(url, headers=headers, json=payload, timeout=300)
    response.raise_for_status()
﻿
    result = response.json()["Response"]
﻿
    if result["Status"] == "Success":
        return result["DocumentRecognizeResultUrl"]
    elif result["Status"] == "Failed":
        raise Exception(f"Parse failed: {result.get('ErrorMessage', 'Unknown error')}")
    else:
        raise Exception(f"Unexpected status: {result['Status']}")
﻿
# 使用示例
try:
    result_url = sync_parse_document(
        file_url="https://example.com/document.pdf",
        file_name="document.pdf",
        file_type="PDF"
    )
    print(f"Parse completed: {result_url}")
﻿
    # 下载结果
    # download_and_extract(result_url)
﻿
except requests.exceptions.Timeout:
    print("Error: Request timeout (file too large or complex)")
except Exception as e:
    print(f"Error: {e}")
Running Environment
Operating System: Ubuntu 24.04.3 LTS / x86_64
Runtime Version: Python 3.11.1
CURL 示例
异步接口调用
提交任务：
curl -X POST https://api.example.com/api/v1/document/parse/submit \\
  -H "Authorization: Bearer your_access_token" \\
  -H "Content-Type: application/json" \\
  -d '{
    "FileType": "PDF",
    "FileName": "example.pdf",
    "FileUrl": "https://qidian-qbot-1251316161.cos.ap-guangzhou.myqcloud.com/public/example/example.pdf"
  }'
查询结果：
curl -X POST https://api.example.com/api/v1/document/parse/query \\
  -H "Authorization: Bearer your_access_token" \\
  -H "Content-Type: application/json" \\
  -d '{
    "TaskId": "236e51fd-827b-41cb-b303-56003a817ce5"
  }'
同步接口调用
同步解析（一次请求获得结果）：
curl -X POST https://api.example.com/api/v1/document/parse/sync_parse \\
  -H "Authorization: Bearer your_access_token" \\
  -H "Content-Type: application/json" \\
  --max-time 300 \\
  -d '{
    "FileType": "PDF",
    "FileName": "example.pdf",
    "FileUrl": "https://qidian-qbot-1251316161.cos.ap-guangzhou.myqcloud.com/public/example/example.pdf"
  }'
说明：
1. --max-time 300：设置请求超时时间为 300 秒（5 分钟），根据文件大小可适当调整。
2. 响应直接返回解析结果，无需额外查询。
注意事项
如有鉴权，鉴权错误码需严格返回401/403，否则会导致无法添加自定义模型。

参数名	类型	必填	说明
Authorization	string	是	Bearer Token 认证
Content-Type	string	是	application/json

错误码	HTTP 状态码	说明
InvalidParameter	400	请求参数错误
InvalidFileUrl	400	文件 URL 无效或无法访问
UnsupportedFileType	400	不支持的文件类型
Unauthorized	401	未授权，Token 缺失
Forbidden	403	Token 无效或已过期
FileTooLarge	413	文件大小超过限制
TooManyRequests	429	请求频率超限
InternalError	500	服务内部错误

状态	说明	建议操作
Pending	任务已提交，等待处理	继续轮询查询
Processing	任务处理中	继续轮询查询
Success	任务成功完成	下载结果文件
Failed	任务失败	查看错误信息，重新提交

字段名	类型	说明
PageNumber	integer	页码，从 1 开始
Angle	integer	页面旋转角度（度）
RotatedAngle	integer	已旋转的角度（度）
Height	integer	页面高度（像素）
Width	integer	页面宽度（像素）
OriginHeight	integer	原始页面高度（像素）
OriginWidth	integer	原始页面宽度（像素）
Elements	array	页面元素列表，详见下方说明

Type	说明	特点
title	标题	通常是文档的章节标题
text	普通文本	段落、正文内容
figure	图表	包含图片、图表等可视化内容，可能包含嵌套的 `figure_text`
figure_text	图表中的文本	图表内部识别出的文本内容
table	表格	结构化的表格数据

ADP 文档解析协议

本页目录：

版本信息

鉴权方式

Bearer Token 认证

接口列表

1. 提交文档解析任务

接口描述

接口地址

请求头（Headers）

请求参数（Request Body）

请求示例

响应参数（Response）

响应示例

错误码说明

2. 查询文档解析结果

接口描述

接口地址

请求头（Headers）

请求参数（Request Body）

请求示例

响应参数（Response）

响应示例

任务状态说明

错误码说明

3. 同步解析接口

接口描述

接口地址

请求头（Headers）

请求参数（Request Body）

请求示例

响应参数（Response）

响应示例

错误码说明

解析结果文件说明

结果文件格式

解析结果文件结构说明

解析页面结构（Page Object）

元素结构（Element Object）

坐标结构（Polygon Object）

元素类型说明

解析结果示例

示例 1：包含标题和图表的页面

示例 2：包含文本和表格的页面

接口调用代码示例

Python 示例

Running Environment

Python 同步接口示例

Running Environment

CURL 示例

异步接口调用

同步接口调用

注意事项