ifly-pdf&image-ocr

基于科大讯飞先进识别 API 的图像与 PDF 文档 AI OCR 服务。

快速开始

图像 OCR（LLM OCR）

# 对图像执行 OCR 并提取文本
python3 scripts/image_ocr.py /path/to/image.jpg

# 将结果保存至文件
python3 scripts/image_ocr.py /path/to/image.jpg -o output.txt

# 指定输出格式
python3 scripts/image_ocr.py /path/to/image.jpg --format json
python3 scripts/image_ocr.py /path/to/image.jpg --format markdown

PDF OCR

# 将 PDF 转换为 Word（默认）
python3 scripts/pdf_ocr.py document.pdf

# 将 PDF 转换为 Markdown
python3 scripts/pdf_ocr.py document.pdf --format markdown

# 将 PDF 转换为 JSON
python3 scripts/pdf_ocr.py document.pdf --format json

# 从公开 URL 处理 PDF
python3 scripts/pdf_ocr.py --pdf-url "https://example.com/doc.pdf" --format word

环境配置

API 凭据

请前往科大讯飞开放平台获取凭据：

图像 OCR 所需凭据：

• APP_ID：应用 ID
• API_KEY：用于身份验证的 API 密钥
• API_SECRET：用于请求签名的 API 密钥

PDF OCR 所需凭据：

• APP_ID：应用 ID
• API_SECRET：用于生成签名的应用密钥

环境变量

# 图像 OCR 和 PDF OCR 均需设置
export IFLY_APP_ID="your_app_id"

# 图像 OCR 必需
export IFLY_API_KEY="your_api_key"

# PDF OCR 必需
export IFLY_API_SECRET="your_api_secret"

功能特性

图像 OCR（LLM OCR）

• AI 驱动：基于先进大语言模型的 OCR，识别精度高
• 多格式输出：支持 JSON、Markdown 或两者同时输出
• 版面理解：保留原始文档结构
• 多语言支持：支持多种语言的文本提取
• 图像预处理：自动校正旋转、去除噪声

PDF OCR

• AI 驱动 OCR：采用先进 AI 模型，实现高精度文本提取
• 多种输出格式：
  • Word (.docx) —— 可编辑的 Word 文档
  • Markdown —— 带格式的纯文本
  • JSON —— 结构化数据
• 大 PDF 支持：单个文档最多支持 100 页
• 逐页结果：可单独访问每一页的识别结果
• 下载链接：提供已处理文件的直连下载地址

API 参数说明

图像 OCR 参数

PDF OCR 参数

*必须提供 pdf_path 或 --pdf-url 中的任意一项

认证方式

图像 OCR（HMAC-SHA256）

采用 HMAC-SHA256 签名认证机制：

1. 生成符合 RFC1123 格式的日期字符串：EEE, dd MMM yyyy HH:mm:ss GMT
2. 构造签名原文：host: {host}\ndate: {date}\nPOST {path} HTTP/1.1
3. 计算签名：HMAC-SHA256(signature_origin, apiSecret)
4. 构造 Authorization 字段：hmac username="{apiKey}", algorithm="hmac-sha256", headers="host date request-line", signature="{signature}"
5. 对 Authorization 字段进行 Base64 编码
6. 作为查询参数发送：?authorization={auth}&host={host}&date={date}

PDF OCR（MD5 + HMAC-SHA1）

采用 MD5 + HMAC-SHA1 签名认证机制：

1. 生成时间戳（Unix 时间戳，单位：秒）
2. 计算 auth = MD5(appId + timestamp)
3. 计算 signature = Base64(HMAC-SHA1(auth, apiSecret))
4. 在请求头中发送以下字段：
   • appId：应用 ID
   • timestamp：时间戳（单位：秒）
   • signature：生成的签名

重要提示：时间戳必须与服务器时间偏差在 ±5 分钟以内。

响应格式

图像 OCR 响应

{
  "header": {
    "code": 0,
    "message": "success"
  },
  "payload": {
    "result": {
      "text": "Base64-encoded OCR text..."
    }
  }
}

PDF OCR 启动响应

{
  "flag": true,
  "code": 0,
  "desc": "成功",
  "data": {
    "taskNo": "25082744936879",
    "status": "CREATE",
    "tip": "任务创建成功"
  }
}

PDF OCR 状态响应

{
  "flag": true,
  "code": 0,
  "desc": "成功",
  "data": {
    "taskNo": "25082759289333",
    "exportFormat": "word",
    "status": "FINISH",
    "downUrl": "http://bjcdn.openstorage.cn/...",
    "tip": "已完成",
    "pageList": [...]
  }
}

任务状态（PDF OCR）

错误码

(｡･ω･｡) 嗨

平台通用错误码

其他资源

• (｡･ω･｡) 服务购买链接：通用文字识别（OCR大模型版）
• (｡･ω･｡) 商务咨询链接：购买服务量

原始 API 错误码

使用限制

图像 OCR

• 支持格式：常见图像格式（JPG、PNG 等）
• 文件大小：适用于网页上传的合理尺寸
• 频率限制：需遵守 API 调用频率限制

PDF OCR

• 最大页数：单个 PDF 最多支持 100 页
• 加密 PDF：不支持受密码保护或加密的 PDF
• 频率限制：状态查询频率限制为每 5 秒一次
• 时间限制：时间戳必须与服务器时间偏差在 ±5 分钟以内

使用建议

图像 OCR

1. 高质量图像：使用清晰、高分辨率图像以获得最佳识别效果
2. 多格式输出：使用 json,markdown 可同时获得结构化数据与带格式文本
3. 保存结果：使用 -o 参数将 OCR 结果保存至本地文件

PDF OCR

1. 数学公式：含数学公式的 PDF 推荐使用 Markdown 输出格式
2. 超大 PDF：若 PDF 超过 100 页，请拆分为多个子文档处理
3. 轮询间隔：状态查询最小间隔为 5 秒
4. 网络 URL：确保提供的 PDF URL 公开可访问
5. 下载时效：下载链接可能过期，请及时下载处理后的文件