API 使用指南

概述

本文描述文档解析服务的 API 接口，支持文件上传、解析任务创建和任务状态查询。系统采用异步处理模式，适用于 WORD、PPT、PDF、图片等文档的智能解析场景。

基础信息

Base URL: https://uniparse.cn-sh-01.sensecoreapi.cn
Content-Type: application/json

接口鉴权

获取API KEY

核心流程

典型使用流程：

获取上传地址 → 2. 上传文件 → 3. 创建解析任务 → 4. 轮询任务状态 → 5. 获取结果

API 接口详情

1. 获取上传文件地址

接口描述：获取文件上传的预签名 URL 和文件唯一标识

POST https://uniparse.cn-sh-01.sensecoreapi.cn/api/v1/files

请求参数

字段	类型	必填	说明
file_name	string	是	文件名称（含扩展名）
file_size	integer	否	文件大小（单位：字节）

请求示例

{
  "file_name": "contract.pdf",
  "file_size": 1048576
}

请求响应

字段	类型	说明
file_id	string	文件唯一标识，后续操作需使用
upload_url	string	预签名上传地址（有效期通常为 15 分钟）

响应示例

{
  "file_id": "file_1234567890abcdef",
  "upload_url": "https://storage.example.com/upload/xxxxxx?signature=xxxxx"
}

使用说明：

获取到 upload_url 后，需使用 PUT 方法上传文件内容
上传请求头需包含 Content-Type: application/octet-stream
上传成功后，文件将与返回的 file_id 绑定

2. 上传文件到指定地址

接口描述：使用获取到的 upload_url 将文件内容上传到对象存储。这是核心步骤，需要特别注意请求方法。

HTTP 请求

PUT https://storage.example.com/upload/xxxxxx?signature=xxxxx

关键说明

项目	要求
HTTP 方法	必须使用 `PUT`，不支持 POST
请求头	`Content-Type: application/octet-stream`（必须）
请求体	文件的原始二进制数据，不要进行 JSON 封装或 Base64 编码
URL 参数	使用获取到的完整 `upload_url`（已包含认证信息），不要额外添加参数
超时设置	建议设置 30-60 秒超时，大文件可适当延长

使用限制

上传 URL 有效期通常为 15 分钟，过期后需重新获取
不要对 upload_url 进行 URL 编码或修改，使用返回的原始地址

3. 创建解析任务

接口描述：提交文档解析任务，系统异步处理

POST https://uniparse.cn-sh-01.sensecoreapi.cn/api/v1/parseTasks

请求参数

字段	类型	必填	说明
file_name	string	是	文件名称
file_id	string	-	文件 ID（与 file_url/file_content 三选一）
file_url	string	-	公开可访问的文件 URL（三选一）
file_content	string	-	Base64 编码的文件内容（三选一）
parse_type	enum	是	解析类型（见下方枚举说明）
page_ranges	string	否	指定解析页码范围，如"1-3,5,7-9"

parse_type 枚举值

值	适用场景	输出特点
PARSE_TYPE_PIPLELINE	合同、报告、论文等长文档	完整结构提取，包含段落、表格、标题层级
PARSE_TYPE_KIE	发票、身份证、表格等结构化文档	关键字段抽取，如姓名、金额、日期等

请求示例

{
  "file_name": "invoice.pdf",
  "file_id": "file_1234567890abcdef",
  "parse_type": "PARSE_TYPE_KIE",
  "page_ranges": "1-5"
}

请求响应

字段	类型	说明
task_id	string	任务唯一标识，用于后续查询
file_name	string	文件名称

响应示例

{
  "task_id": "task_abcdef1234567890",
  "file_name": "invoice.pdf"
}

注意事项：

必须且仅提供 file_id、file_url、file_content 中的一种
file_content 需为 Base64 编码字符串，适用于小文件（<10MB）
大文件建议使用 file_id 方式（先上传后解析）

4. 获取解析任务信息

接口描述：查询任务执行状态、进度和结果

GET https://uniparse.cn-sh-01.sensecoreapi.cn/api/v1/parseTasks/{task_id}

路径参数

参数	类型	说明
task_id	string	任务 ID（创建任务时返回）

请求响应

字段	类型	说明
task_id	string	任务 ID
file_name	string	文件名称
batch_id	string	批次 ID（用于批量查询）
parse_type	enum	解析类型
page_ranges	string	页码范围
state	enum	任务状态（见下方枚举说明）
error_message	string	错误信息（仅失败时有效）
total_pages	integer	总页数
parsed_pages	integer	成功解析页数
failed_pages	integer	失败页数
result_zip_url	string	结果压缩包下载地址（成功后生成）
result_json	string	解析结果 JSON（成功后生成）
created_at	string	创建时间
updated_at	string	更新时间
finished_at	string	完成时间

state 枚举值

值	说明
TASK_STATE_UNSPECIFIED	未指定
TASK_STATE_PENDING	排队中
TASK_STATE_RUNNING	解析中
TASK_STATE_SUCCEEDED	解析成功
TASK_STATE_FAILED	解析失败
TASK_STATE_CANCELED	已取消

响应示例（运行中）

{
  "task_id": "task_abcdef1234567890",
  "file_name": "invoice.pdf",
  "batch_id": "batch_20241107",
  "parse_type": "PARSE_TYPE_KIE",
  "state": "TASK_STATE_RUNNING",
  "total_pages": 10,
  "parsed_pages": 6,
  "failed_pages": 0,
  "created_at": "2024-11-07T10:00:00Z",
  "updated_at": "2024-11-07T10:05:30Z"
}

响应示例（成功）

{
  "task_id": "task_abcdef1234567890",
  "file_name": "invoice.pdf",
  "parse_type": "PARSE_TYPE_KIE",
  "state": "TASK_STATE_SUCCEEDED",
  "total_pages": 10,
  "parsed_pages": 10,
  "failed_pages": 0,
  "result_zip_url": "https://storage.example.com/results/task_abcdef.zip?token=xxx",
  "result_json": "{\"pages\": [...]}",
  "created_at": "2024-11-07T10:00:00Z",
  "finished_at": "2024-11-07T10:08:15Z"
}

轮询建议：任务状态查询建议间隔 5-10 秒，避免频繁请求

完整调用示例

cURL 示例

# 1. 获取上传地址
curl -X POST https://uniparse.cn-sh-01.sensecoreapi.cn/api/v1/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '{"file_name":"sample.pdf","file_size":2048000}'

# 2. 上传文件（假设上一步返回的 upload_url）
curl -X PUT "https://storage.example.com/upload/xxxxxx" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @sample.pdf

# 3. 创建解析任务
curl -X POST https://uniparse.cn-sh-01.sensecoreapi.cn/api/v1/parseTasks \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $API_TOKEN" \
  -d '{"file_name":"sample.pdf","file_id":"file_123456","parse_type":"PARSE_TYPE_PIPLELINE"}'

# 4. 查询任务状态
curl https://uniparse.cn-sh-01.sensecoreapi.cn/api/v1/parseTasks/task_abcdef1234567890 \
  -H "Authorization: Bearer $API_TOKEN" 

Python 示例

import requests
import json
import time
import sys
import os

BASE_URL = "https://uniparse.cn-sh-01.sensecoreapi.cn"
TOKEN = "sk-xxxxxxxxx"

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

def upload_and_parse(file_path, parse_type="PARSE_TYPE_PIPLELINE"):
    # 1. 获取上传地址
    file_name = file_path.split("/")[-1]
    file_size = os.path.getsize(file_path)
    
    resp = requests.post(
        f"{BASE_URL}/api/v1/files",
        json={"file_name": file_name, "file_size": file_size},
        headers=headers
    )
    upload_info = resp.json()
    file_id = upload_info["file_id"]
    upload_url = upload_info["upload_url"]
    
    # 2. 上传文件
    with open(file_path, "rb") as f:
        requests.put(upload_url, data=f, headers={"Content-Type": "application/octet-stream"})
    
    # 3. 创建解析任务
    task_resp = requests.post(
        f"{BASE_URL}/api/v1/parseTasks",
        json={
            "file_name": file_name,
            "file_id": file_id,
            "parse_type": parse_type
        },
        headers=headers
    )
    task = task_resp.json()
    task_id = task["task_id"]
    
    # 4. 轮询等待完成
    while True:
        status_resp = requests.get(f"{BASE_URL}/api/v1/parseTasks/{task_id}",headers=headers)
        status = status_resp.json()
        
        print(f"状态: {status['state']}, 进度: {status['parsed_pages']}/{status['total_pages']}")
        
        if status["state"] == "TASK_STATE_SUCCEEDED":
            print("解析完成！")
            print(f"结果下载: {status['result_zip_url']}")
            return status
        elif status["state"] in ["TASK_STATE_FAILED", "TASK_STATE_CANCELED"]:
            raise Exception(f"任务失败: {status['error_message']}")
        
        time.sleep(3)

# 使用示例
result = upload_and_parse("invoice.pdf", "PARSE_TYPE_PIPLELINE")

状态流转

PENDING → RUNNING → SUCCEEDED
                 ↘ FAILED
                 ↘ CANCELED

错误处理

HTTP 状态码

错误码参考

业务错误

任务失败时，state 为 TASK_STATE_FAILED，error_message 字段会包含具体原因：

{
  "state": "TASK_STATE_FAILED",
  "error_message": "文件格式不支持或文件已损坏",
  "finished_at": "2024-11-07T10:10:00Z"
}

最佳实践

文件大小限制：建议单文件不超过 100MB，大文件请分割处理
超时处理：上传 URL 通常 15 分钟过期，请及时上传
结果保留：解析结果仅保留 7 天，请及时下载
并发控制：请避免一次性提交过多任务，会长时间处于pending状态，或返回 429 状态码
幂等设计：如创建任务失败，建议使用新 file_id 重试，避免重复提交
错误重试：对 TASK_STATE_FAILED 状态，根据错误信息决定是否重试

常见问题

Q: upload_url 如何使用？ A: 必须使用 HTTP PUT 方法上传原始二进制文件，不能使用 POST 或 multipart/form-data。

Q: 如何获取 file_url？ A: file_url 需是公开可访问的 HTTP/HTTPS 地址，适用于文件已存储在第三方云存储的场景。

Q: result_json 和 result_zip_url 的区别？ A: result_json 直接返回解析结果（适合小文件），result_zip_url 提供打包下载链接（适合大文件或含图片资源）。

Q: 任务长时间卡在 PENDING 状态？ A: 系统资源繁忙时可能需要排队，通常 1-2 分钟内会开始执行。若超过 30 分钟仍为 PENDING，请联系技术支持。

技术支持

服务状态：检查系统健康状态
问题反馈：提供 task_id 和请求时间以便排查

API 使用指南

概述​

基础信息​

接口鉴权​

核心流程​

API 接口详情​

1. 获取上传文件地址​

2. 上传文件到指定地址​

3. 创建解析任务​

4. 获取解析任务信息​

完整调用示例​

cURL 示例​

Python 示例​

状态流转​

错误处理​

HTTP 状态码​

业务错误​

最佳实践​

常见问题​

技术支持​

概述

基础信息

接口鉴权

核心流程

API 接口详情

1. 获取上传文件地址

2. 上传文件到指定地址

3. 创建解析任务

4. 获取解析任务信息

完整调用示例

cURL 示例

Python 示例

状态流转

错误处理

HTTP 状态码

业务错误

最佳实践

常见问题

技术支持