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）

请求参数（Request Body）

请求示例

{  "FileType": "PDF",  "FileName": "example.pdf",  "FileUrl": "https://example.cos.ap-guangzhou.myqcloud.com/public/example/example.pdf"}

响应参数（Response）

响应示例

成功响应（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"  }}

错误码说明

2. 查询文档解析结果

接口描述

根据 TaskId 查询文档解析任务的状态和结果。解析完成后会返回结果文件的下载地址。

接口地址

POST https://api.example.com/api/v1/document/parse/query

请求头（Headers）

请求参数（Request Body）

请求示例

{  "TaskId": "236e51fd-827b-41cb-b303-56003a817ce5"}

响应参数（Response）

响应示例

成功响应 - 任务完成（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"  }}

任务状态说明

错误码说明

3. 同步解析接口

接口描述

提交一个文档解析任务，支持 PDF、Word、Excel、PPT 等多种文档格式。任务提交后会返回 TaskId，用于后续查询解析结果。

接口地址

POST https://api.example.com/api/v1/document/parse/sync_parse

请求头（Headers）

请求参数（Request Body）

请求示例

{  "FileType": "PDF",  "FileName": "example.pdf",  "FileUrl": "https://example.cos.ap-guangzhou.myqcloud.com/public/example/example.pdf"}

响应参数（Response）

响应示例

成功响应 - 任务完成（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"  }}

错误码说明

解析结果文件说明

结果文件格式

解析完成后，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）

元素结构（Element Object）

坐标结构（Polygon Object）

坐标系说明：

原点 (0, 0) 位于页面左上角。

X 轴向右递增。

Y 轴向下递增。

元素类型说明

解析结果示例

示例 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_64Runtime 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_64Runtime 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"  }'

说明：

--max-time 300：设置请求超时时间为 300 秒（5 分钟），根据文件大小可适当调整。

响应直接返回解析结果，无需额外查询。

注意事项

如有鉴权，鉴权错误码需严格返回401/403，否则会导致无法添加自定义模型。