Parse4ai 文档

常见问题解答（FAQ）

基础问题

什么是文档解析服务？

文档解析服务是一个基于 AI 的智能文档处理平台，可以自动提取 PDF、Word、PPT 等文档中的文本、表格、公式和图片等内容，并转换为结构化数据。

支持哪些文档格式？

目前支持以下格式：

PDF (.pdf)
Word (.doc, .docx)
PowerPoint (.ppt, .pptx)
图片 (.png, .jpg, .jpeg)

文件大小和页数限制是多少？

试用模式：最大 5MB，仅解析第一页
正式模式：最大 200MB，最多 600 页

注意：

单个文件大小不能超过 200MB
文件页数不能超出 600 页
因网络限制，github、aws 等国外 URL 可能会请求超时
该接口不支持文件直接上传，需要提供可访问的文件 URL

使用问题

如何获取 API 密钥？

注册并登录账户
进入 API 密钥管理页面
点击"创建新密钥"按钮
复制生成的密钥并妥善保管

如何进行 API 认证？

所有 API 请求需要在 HTTP 请求头中包含 Authorization 字段：

Authorization: Bearer YOUR_API_KEY

格式为 Bearer + 空格 + 您的 API 密钥。

解析一份文档需要多长时间？

解析时间取决于文档的大小和复杂度：

简单文档（10 页以内）：通常 5-15 秒
中等文档（10-50 页）：通常 30-60 秒
大型文档（50-600 页）：通常 2-10 分钟

如何提高解析准确率？

使用高质量的原始文档：避免扫描件或低分辨率图片
启用 OCR 功能：对于扫描件或图片格式的文档，设置 is_ocr: true
选择正确的语言：在请求中指定文档语言（language 参数），默认支持中文（ch）
确保文档格式正确：避免损坏或加密的文件
启用公式和表格识别：设置 enable_formula: true 和 enable_table: true

支持批量解析吗？

目前 API 仅支持单个文件解析。如需批量处理，请循环调用创建任务接口。

如何指定解析特定页面？

您可以在创建任务时使用 pageRanges 参数指定页码范围，格式为逗号分隔的字符串：

"1-5"：表示第 1 页到第 5 页
"2,4-6"：表示第 2 页、第 4 页至第 6 页
"2--2"：表示从第 2 页到倒数第二页

计费问题

如何计费？

我们按照解析的页数进行计费：

免费版：每月 50 页免费额度
专业版：每月 1000 页起
企业版：自定义额度

具体价格请查看价格页面。

解析失败会扣费吗？

不会。只有成功完成解析的页数才会计入使用量。如果任务创建失败或解析失败，不会扣除您的额度。

额度用完了怎么办？

您可以：

升级到更高级的套餐
购买额外的额度包
联系我们定制企业方案

每个账号的解析额度有限制吗？

每个账号每天享有 2000 页最高优先级解析额度，超过 2000 页的部分优先级可能会降低。

技术问题

API 端点是什么？

基础 URL: /api/v1/extract

创建任务: POST /api/v1/extract/task

查询任务: GET /api/v1/extract/task/{taskId}

如何处理大文件？

对于大文件，我们建议：

使用 callback 参数配置 Webhook 接收完成通知，而不是频繁轮询
如果可能，将大文件拆分为多个小文件
确保文件 URL 可正常访问，避免超时

支持 Webhook 回调吗？

是的，您可以在创建任务时提供 callback 参数，解析完成后我们会向该 URL 发送 POST 请求。

注意事项：

callback 接口必须支持 POST 方法、UTF-8 编码、Content-Type: application/json
当使用 callback 时，必须同时提供 seed 参数用于签名校验
callback 接口返回 HTTP 200 状态码表示接收成功
如果接收失败，系统最多会重复推送 5 次

详见 Webhooks 文档。

API 有速率限制吗？

是的，为了保证服务质量：

免费版：10 次/分钟
专业版：60 次/分钟
企业版：可定制

如何处理错误？

所有 API 响应都包含 code 和 message 字段：

code = 0 表示成功
code != 0 表示失败，message 包含错误信息

常见错误码：

错误码	说明	解决建议
-20002	Token 错误	检查 Token 是否正确，请检查是否有 Bearer 前缀或更换新 Token
-20011	Token 过期	更换新 Token
-500	传参错误	请确保参数类型及 Content-Type 正确
-10001	服务异常	请稍后再试
-10002	请求参数错误	检查请求参数格式
-60002	获取匹配的文件格式失败	检测文件类型失败，请求的文件名及链接中带有正确的后缀名
-60003	文件读取失败	请检查文件是否损坏并重新上传
-60004	空文件	请上传有效文件
-60005	文件大小超出限制	检查文件大小，最大支持 200MB
-60006	文件页数超过限制	请拆分文件后重试
-60007	模型服务暂时不可用	请稍后重试或联系技术支持
-60008	文件读取超时	检查 URL 可访问
-60009	任务提交队列已满	请稍后再试
-60010	解析失败	请稍后再试
-60012	找不到任务	请确保 taskId 有效且未删除
-60013	没有权限访问该任务	只能访问自己提交的任务
-60015	文件转换失败	可以手动转为 PDF 再上传
-60017	页码余额不足	请充值或升级套餐

任务状态有哪些？

任务状态包括：

pending: 排队中
running: 正在解析
converting: 格式转换中
done: 解析完成
failed: 解析失败

解析结果包含哪些内容？

解析完成后，您可以通过 fullZipUrl 获取完整的解析结果压缩包，其中包含：

Markdown 格式的文档内容（默认格式）
JSON 格式的结构化数据（默认格式）
可选择导出为 docx、html、latex 等格式（需设置 extraFormats 参数）

安全与隐私

我的文档安全吗？

是的，我们非常重视数据安全：

所有 API 通信使用 HTTPS 加密
文档处理完成后会在一定时间内自动删除
我们不会将您的文档用于其他用途

可以立即删除解析结果吗？

是的，您可以在用户中心手动删除解析结果，或联系我们的客服团队。

是否支持私有部署？

企业版支持私有部署，请联系我们的销售团队了解详情。

获取帮助

还有其他问题？

如果您有其他问题，可以：

查看完整 API 文档
联系客服：support@parse4ai.com
加入我们的社区讨论群

如何报告 Bug？

请发送邮件到 support@parse4ai.com，包含以下信息：

详细的问题描述
重现步骤
相关的任务 ID 或 trace_id
错误信息截图