# EasyLink EasyDoc-Parse 智能文档解析

## 概述

EasyDoc-Parse 是一个智能文档解析模型。上传文档（PDF/图片）后，模型会自动识别文档结构，返回包含标题、文本、表格、图形等节点信息的结构化 JSON，以及 Markdown 格式内容，适用于文档数字化、内容提取、RAG 知识库构建等场景。

本接口为异步模式：提交任务后获得任务 ID，通过轮询接口查询结果。解析结果以文件形式存储，通过 `output.urls[0]` 返回下载链接，有效期 7 天。

更多细节请参考 [EasyLink 官方文档](https://docs.easylink-ai.com/docs/capabilities/parsing/api-v2)。

**请求地址**：`https://api.modelverse.cn/v1/tasks/submit`

## 支持模型

- `easydoc-parse-premium`

## 请求参数

### 提交任务

| 字段 | 类型 | 是否必需 | 说明 |
| :--- | :--- | :--- | :--- |
| model | string | 是 | 模型名称，固定为 `easydoc-parse-premium` |
| input.img_url | string | 是 | 待解析文件的 URL，支持 PDF / JPG / PNG / BMP / TIFF |

### 查询任务状态

| 字段 | 类型 | 是否必需 | 说明 |
| :--- | :--- | :--- | :--- |
| task_id | string | 是 | 提交任务时返回的任务 ID |

## 响应字段

### 提交响应

| 字段 | 类型 | 说明 |
| :--- | :--- | :--- |
| output.task_id | string | 任务 ID，用于后续查询 |
| request_id | string | 请求 ID |

### 状态查询响应

| 字段 | 类型 | 说明 |
| :--- | :--- | :--- |
| output.task_status | string | 任务状态：`Pending` / `Running` / `Success` / `Failure` |
| output.urls | array | 解析结果文件的下载链接列表（成功时返回，有效期 7 天） |
| output.error_message | string | 错误信息（失败时返回） |
| usage.page_count | integer | 文件页数，用于计费 |

`output.urls[0]` 下载后得到的 JSON 结构：

| 字段 | 类型 | 说明 |
| :--- | :--- | :--- |
| file_name | string | 文件名 |
| nodes | array | 文档节点数组，见下方说明 |
| markdown | string | Markdown 格式的文档内容 |

`nodes` 每个元素的结构：

| 字段 | 类型 | 说明 |
| :--- | :--- | :--- |
| id | integer | 节点 ID |
| type | string | 节点类型：`Title`（标题）/ `Text`（文本）/ `Table`（表格）/ `Figure`（图形） |
| text | string | 节点文本内容 |
| parent_id | integer | 父节点 ID，`-1` 表示根节点 |
| composing_blocks | array | 坐标位置信息，包含 `page_number`、`coordinates [x1,y1,x2,y2]`、`layout_width`、`layout_height` |
| path_info | object | 节点路径信息 |

## 示例

### Curl 示例

**提交任务：**

```bash
curl -X POST https://api.modelverse.cn/v1/tasks/submit \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "easydoc-parse-premium",
    "input": {
      "img_url": "https://example.com/document.pdf"
    }
  }'
```

**查询任务状态：**

```bash
curl "https://api.modelverse.cn/v1/tasks/status?task_id={task_id}" \
  -H "Authorization: Bearer {api_key}"
```

**下载解析结果：**

```bash
curl "{output.urls[0]}" -o result.json
```

### Python 示例

```python
import json
import time
import requests

api_key = "******"  # 替换为你的 API Key
base_url = "https://api.modelverse.cn/v1"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json",
}

# 提交任务
submit_data = {
    "model": "easydoc-parse-premium",
    "input": {
        "img_url": "https://example.com/document.pdf",
    },
}

resp = requests.post(f"{base_url}/tasks/submit", headers=headers, json=submit_data)
task_id = resp.json()["output"]["task_id"]
print(f"task_id: {task_id}")

# 轮询查询结果
while True:
    result = requests.get(
        f"{base_url}/tasks/status",
        headers=headers,
        params={"task_id": task_id},
    ).json()

    status = result["output"]["task_status"]
    print(f"status: {status}")

    if status == "Success":
        download_url = result["output"]["urls"][0]
        print(f"结果下载链接: {download_url}")
        parsed = requests.get(download_url).json()
        print(f"文件名: {parsed['file_name']}")
        print(f"节点数量: {len(parsed['nodes'])}")
        print(f"总页数: {result['usage']['page_count']}")
        break
    elif status == "Failure":
        print(f"失败: {result['output'].get('error_message')}")
        break

    time.sleep(10)
```

## 响应示例

**提交成功：**

```json
{
  "output": {
    "task_id": "parse_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

**任务完成：**

```json
{
  "output": {
    "task_id": "parse_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "task_status": "Success",
    "urls": [
      "https://text-store.cn-wlcb.ufileos.com/easylink/parse/parse_xxxxxxxx.json?Expires=xxxxxxxxxx&Signature=xxx&UCloudPublicKey=xxx"
    ],
    "submit_time": 1700000000,
    "finish_time": 1700000060
  },
  "usage": {
    "duration": 60,
    "page_count": 5
  },
  "request_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
```

**下载链接返回的 JSON 结构示例：**

```json
{
  "file_name": "document.pdf",
  "nodes": [
    {
      "id": 1,
      "type": "Title",
      "text": "文档标题",
      "parent_id": -1,
      "composing_blocks": [
        {
          "page_number": 1,
          "coordinates": [582, 271, 1121, 328],
          "system": "PixelSpace",
          "layout_width": 1708,
          "layout_height": 2212
        }
      ],
      "path_info": {
        "path_context": "",
        "path": []
      }
    }
  ],
  "markdown": "# 文档标题\n\n正文内容..."
}
```

## 使用说明

1. **文件格式**：支持 PDF、JPG、PNG、BMP、TIFF，通过 `input.img_url` 传入文件的公网访问地址。
2. **结果获取**：任务成功后，`output.urls[0]` 是解析结果 JSON 文件的下载链接，需要额外发起一次请求下载才能获取结构化内容。
3. **链接有效期**：下载链接有效期为 7 天，请及时下载保存。
4. **计费**：按文件页数计费，页数通过 `usage.page_count` 返回。