星辰文档解析 (算法编码：8000400022)

协议类型：HTTPS

---

一、接入点

1.1 文档解析接口

环境	地址
公网	https://api-maas.teleai.com.cn

• API Path ：/aipaas/ocr/v1/xingchenOcr/multimodal
• 请求方法 ：POST
• Content-Type ：application/json

1.2 解析结果查询接口（Pull 模式）

• API Path ：/aipaas/lm/v1/asyncResult/query
• 请求方法 ：GET
• Content-Type ：application/json

---

二、鉴权

采用请求头携带鉴权信息：

2.1 标准鉴权

Authorization: <鉴权信息>

• 鉴权规则请参见：开发指南 - 签名认证方式。
• 鉴权在线生成工具：API在线签名计算工具。

请求头	必填	说明
Content-Type	否	内容类型，固定 application/json
X-APP-ID	否	取值为控制台 → 应用及API Key → 创建应用 → AppID
Device-Uuid	否	设备uuid
Authorization	是	鉴权信息

2.2 Bearer Token 鉴权

Authorization: Bearer <用户申请的API-KEY>

• API Key 鉴权，请在 API Key 管理 页面，获取长效 API Key。

请求头	必填	说明
Content-Type	否	内容类型，固定 application/json
Device-Uuid	否	设备uuid
Authorization	是	Bearer <API_KEY>

---

三、能力简介

星辰文档解析接口提供图像和 PDF 文档的结构化解析能力，支持版面分析、文字识别、表格提取、公式识别和图片提取，输出 Markdown 格式结果及结构化 JSON 数据。

• 支持文件格式：JPG、JPEG、PNG、BMP、WebP、PDF
• 支持多页文档解析，无页数限制
• 文件编码后大小不超过 10M
• 图片最短边至少 15px，分辨率不超过 3840×3840
• 输出包含版面坐标、文本内容、图片 URL、表格 HTML 等
• 支持 Push（主动推送）和 Pull（客户端拉取）两种结果获取模式

3.1 修订历史

修订日期	算法版本号	修订内容
2026-10-23	8000400022	初始版本

---

四、请求与响应

4.1 请求参数

4.1.1 顶层字段

字段	类型	必填	说明
seqid	string	是	接口跟踪 ID，每次调用需不同，最短 1 字符最长 32 位
image	string	是	图像/PDF 的 Base64 编码或 URL，由 image_type 指定。详见下方 image 字段限制
image_type	int	否	0：image 为 URL（默认）；1：image 为 Base64 编码
return_mode	int	否	结果获取方式。0：Push 模式，服务端主动推送至 callback_url（默认）；1：Pull 模式，客户端通过查询接口拉取结果
callback_url	string	否	回调地址，Push 模式（return_mode=0）下用于接收解析结果推送；return_mode传入为0时，callback_url为必填
needed_pages	array	否	指定解析页码。数组元素可为 int（单页）或 [int, int]（起止页码，含两端）。例如 [3, [5, 9]] 表示解析第 3、5、6、7、8、9 页。页码从 0 开始。默认解析所有页
html_escape	boolean	否	是否对输出内容进行 HTML 转义，用于防范 XSS 漏洞，默认 true

image 字段限制：

• 编码后大小不超过 10M
• 图片最短边至少 15px（内部未做强制限制，过小可能识别不到结果）
• 分辨率不超过 3840×3840（内部未做强制限制，超过此分辨率可能有未知异常）
• 支持格式：JPG、JPEG、PNG、BMP、WebP、PDF
• 支持多页文档，无页数限制
• URL 须以 http:// 或 https:// 开头

4.2 响应体

4.2.1 顶层字段

字段	类型	说明
seqid	string	请求序列号，请求的唯一标识，透传
code	string	状态响应码
message	string	调用结果描述
flag	int	业务标识：1 成功，0 失败
data	object	解析结果。Push 模式下结果会被推送到 callback_url；Pull 模式下需通过查询接口获取

4.2.2 data

字段	类型	说明
timeSecond	double	分析耗时（秒）
words_result	array	所有识别结果

4.2.3 data > words_result[]

字段	类型	说明
total_page_number	int	解析总页数
markdown	string	Markdown 格式的识别结果
pages	array	各页解析内容

4.2.4 words_result[] > pages[]

字段	类型	说明
page_id	int	页码，从 0 开始
width	int	页面宽度（像素）
height	int	页面高度（像素）
discarded_blocks	array	页眉页脚信息，无则为空列表。详见 4.2.5
content	array	内容块数组。详见 4.2.6

4.2.5 pages[] > discarded_blocks[]

字段	类型	说明
type	string	页眉页脚类型：header 或 footer
angle	int	文本旋转角度
index	int	当前页内块序号，从 0 开始，不一定连续
pos	array[int]	版面块坐标 [x0, y0, x1, y1]，左上角为坐标原点
text	string	OCR 识别文本内容

4.2.6 pages[] > content[] — 通用字段

所有内容块均包含以下字段：

字段	类型	说明
type	string	内容块类型：text、title、image、table、equation
angle	int	文本旋转角度
index	int	当前页内块序号，从 0 开始，不一定连续
pos	array[int]	版面块坐标 [x0, y0, x1, y1]，左上角为坐标原点

各类型额外字段：

• text / title / equation：额外包含 text（string）— OCR 识别文本内容
• image：额外包含 blocks（array）— 图片块数组，详见 4.2.7
• table：额外包含 blocks（array）— 表格块数组，详见 4.2.8

4.2.7 content[] > blocks[]（type 为 image 时）

blocks 数组长度为 1 或 2，一定包含 image_body，可能包含 image_caption。

字段	类型	说明
type	string	块类型：image_body 或 image_caption
angle	int	文本旋转角度
index	int	当前页内块序号，从 0 开始，不一定连续
pos	array[int]	版面块坐标 [x0, y0, x1, y1]，左上角为坐标原点
image_url	string	图片 URL（仅 type 为 image_body 时存在。若上传 S3 失败，该 URL 无意义）
content	string	图片标题文本（仅 type 为 image_caption 时存在）

4.2.8 content[] > blocks[]（type 为 table 时）

blocks 数组一定包含 table_body，可能包含 table_caption。

字段	类型	说明
type	string	块类型：table_body 或 table_caption
angle	int	文本旋转角度
index	int	当前页内块序号，从 0 开始，不一定连续
pos	array[int]	版面块坐标 [x0, y0, x1, y1]，左上角为坐标原点
image_url	string	表格图片 URL（仅 type 为 table_body 时存在）
html	string	HTML 格式的表格信息（仅 type 为 table_body 时存在）
content	string	表格标题文本（仅 type 为 table_caption 时存在）

4.3 解析结果查询接口（Pull 模式）

当 return_mode=1 时，客户端通过本接口主动拉取解析结果。

4.3.1 请求参数

参数名	位置	类型	必填	说明
requestId	Query	string	是	请求唯一标识，调用/aipaas/ocr/v1/xingchenOcr/multimodal 接口时返回

示例：

GET /aipaas/lm/v1/asyncResult/query?requestId=REQ_17763255011822

4.3.2 响应体

响应体结构同主接口响应体，详见 4.2。

---

五、交互流程

5.1 Push 模式（return_mode = 0）

1. 客户端调用 POST /aipaas/ocr/v1/xingchenOcr/multimodal，设置 return_mode=0 并提供 callback_url。
2. 服务端接收请求并处理。
3. 服务端将解析结果推送到 callback_url。

5.2 Pull 模式（return_mode = 1）

1. 客户端调用 POST /aipaas/ocr/v1/xingchenOcr/multimodal，设置 return_mode=1。
2. 服务端返回请求唯一标识 requestId。
3. 客户端调用 GET /aipaas/lm/v1/asyncResult/query?requestId={requestId} 查询结果。
4. 查询接口响应体结构同主接口响应体。

---

六、状态码说明

6.1 算法状态码

状态码	说明	描述	解决方法
10000	请求成功	调用成功	—
10202	算法推理异常	算法推理失败	检查输入文件是否有效，重试；若持续失败请联系技术支持
10203	文件上传异常	结果图片上传 ceph/minIO 失败	重试；若持续失败请联系技术支持
10304	服务入参错误	针对入参做校验返回	检查请求参数是否符合接口规范
10903	服务执行失败	可能存在组件连接异常、算法模型程序运行异常等	重试；若持续失败请联系技术支持

6.2 公共状态码

• 接口响应的公共状态码由网关统一定义，一般用于标识鉴权失败、限流或服务异常，具体业务错误码、错误信息及排查建议请参考：开发指南-公共信息及状态码。

---

七、调用示例

7.1 请求示例

{
    "image": "/9j/4AA****    **2Q==",
    "seqid": "REQ_17763255011823",
    "return_mode": 1,
    "image_type": 1,
    "callback_url": "http://x.com",
    "html_escape": false
}

7.2 成功响应示例

{
    "seqid": "test_seq0",
    "code": "10000",
    "message": "请求成功",
    "flag": 1,
    "data": {
        "timeSecond": 1.25,
        "words_result": [{
            "total_page_number": 2,
            "markdown": "识别markdown格式数据",
            "pages": [{
                "page_id": 0,
                "width": 1654,
                "height": 2339,
                "discarded_blocks": [],
                "content": [
                    {
                        "type": "text",
                        "angle": 0,
                        "index": 0,
                        "pos": [100, 120, 500, 200],
                        "text": "示例文本"
                    },
                    {
                        "type": "image",
                        "angle": 0,
                        "blocks": [
                            {
                                "type": "image_body",
                                "angle": 0,
                                "index": 5,
                                "pos": [60, 214, 536, 426],
                                "image_url": "/images/..."
                            },
                            {
                                "type": "image_caption",
                                "angle": 0,
                                "index": 7,
                                "pos": [46, 431, 547, 464],
                                "content": "Figure 1. ..."
                            }
                        ]
                    },
                    {
                        "type": "table",
                        "angle": 0,
                        "blocks": [
                            {
                                "type": "table_body",
                                "angle": 0,
                                "index": 4,
                                "pos": [271, 649, 1589, 1975],
                                "html": "html格式的表格数据",
                                "image_url": "http://..."
                            }
                        ],
                        "index": 4,
                        "pos": [271, 649, 1589, 1975]
                    }
                ]
            }]
        }]
    }
}

7.3 Python

import requests
import time
import uuid

url = "https://openapi.teleagi.cn/aipaas/ocr/v1/xingchenOcr/multimodal"

headers = {
    "Content-Type": "application/json",
    "X-APP-ID": "your_app_id",
    "Authorization": "your_authorization",
    "Device-Uuid": str(uuid.uuid4())
}

payload = {
    "image": "https://example.com/document.pdf",
    "seqid": "REQ_" + str(int(time.time() * 1000)),
    "return_mode": 1,
    "image_type": 0,
    "html_escape": True
}

start = time.time()
response = requests.post(url, json=payload, headers=headers, stream=True)
ttfb = time.time() - start

print(f"TTFB: {ttfb:.3f}s")
print(f"Status: {response.status_code}")

result = response.json()
print(f"Code: {result.get('code')}")
print(f"Message: {result.get('message')}")
print(f"Flag: {result.get('flag')}")

if result.get("flag") == 1 and result.get("data"):
    data = result["data"]
    print(f"Time: {data.get('timeSecond')}s")
    for wr in data.get("words_result", []):
        print(f"Total pages: {wr.get('total_page_number')}")
        print(f"Markdown: {wr.get('markdown', '')[:200]}")

7.4 Java

import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.JSONObject;
import java.util.HashMap;
import java.util.Map;

public class XingchenOcrDemo {
    public static void main(String[] args) {
        String url = "https://openapi.teleagi.cn/aipaas/ocr/v1/xingchenOcr/multimodal";

        Map<String, Object> body = new HashMap<>();
        body.put("image", "https://example.com/document.pdf");
        body.put("seqid", "REQ_" + System.currentTimeMillis());
        body.put("return_mode", 1);
        body.put("image_type", 0);
        body.put("html_escape", true);

        HttpResponse response = HttpRequest.post(url)
            .header("Content-Type", "application/json")
            .header("X-APP-ID", "your_app_id")
            .header("Authorization", "your_authorization")
            .body(JSON.toJSONString(body))
            .timeout(60000)
            .execute();

        JSONObject result = JSON.parseObject(response.body());
        System.out.println("Code: " + result.getString("code"));
        System.out.println("Message: " + result.getString("message"));
        System.out.println("Flag: " + result.getInteger("flag"));

        JSONObject data = result.getJSONObject("data");
        if (data != null) {
            System.out.println("Time: " + data.getDouble("timeSecond"));
        }
    }
}