Python SDK

DocParse4AI 内置 Python SDK，封装同步/异步解析与用量查询，可直接复制到业务项目中使用。

安装依赖

SDK 位于 lwsomark-api/lwsomark_sdk/，仅需 httpx：

cd lwsomark-api
pip install httpx

# 或将 lwsomark-api 加入 PYTHONPATH
export PYTHONPATH=/path/to/lwsomark-api:$PYTHONPATH

快速开始

from lwsomark_sdk import SoMarkClient, SoMarkError

client = SoMarkClient(
    base_url="https://www.docparse4ai.com",
    api_key="sk-dev",
)

# 同步解析
data = client.parse_sync(
    "document.pdf",
    output_formats=["markdown", "json"],
    scene="general",
    feature_config={"enable_title_level_recognition": True},
)
markdown = data["result"]["outputs"]["markdown"]
print(markdown[:500])

API 方法

参数	类型	必填	说明
parse_sync(file, **opts)	method	否	同步解析，返回 data 字典
parse_async_submit(file, **opts)	method	否	提交异步任务，返回 task_id
parse_async_check(task_id)	method	否	轮询任务状态（QUEUING/PROCESSING/SUCCESS/FAILED）
parse_async_wait(file, poll_interval=3)	method	否	提交并阻塞等待 SUCCESS
usage()	method	否	查询剩余免费/付费页数
health()	method	否	服务健康检查（扩展接口）

异步解析示例

# 方式一：手动轮询
task_id = client.parse_async_submit("large.pdf", output_formats=["markdown"])
while True:
    data = client.parse_async_check(task_id)
    if data["status"] == "SUCCESS":
        print(data["result"]["outputs"]["markdown"])
        break
    if data["status"] == "FAILED":
        raise RuntimeError(data.get("error"))
    time.sleep(3)

# 方式二：一键等待
data = client.parse_async_wait("large.pdf", poll_interval=3, max_wait=600)
print(f"record_id={data['record_id']}")

错误处理

from lwsomark_sdk import SoMarkError

try:
    client.parse_sync("bad.xyz")
except SoMarkError as e:
    print(e.code)      # 1104
    print(e.message)   # 不支持的文件格式

错误码说明见错误码参考。

命令行示例

项目内置可运行脚本（需 API 服务已启动）：

cd lwsomark-api
python scripts/sdk_example.py path/to/document.pdf

可选参数

所有解析方法均支持以下关键字参数（对齐 SoMark API）：

output_formats — ["markdown", "json", "zip"]
element_formats — 图片/公式/表格格式 dict
feature_config — 跨页拼接、标题层级等开关
scene — 固定为 general（默认）；k12 已废弃