ifly-pdf-image-ocr

AI-powered OCR service for images and PDF documents using iFlytek's advanced recognition APIs.

Quick Start

Image OCR (LLM OCR)

# OCR an image and extract text
python3 scripts/image_ocr.py /path/to/image.jpg

# Save result to file
python3 scripts/image_ocr.py /path/to/image.jpg -o output.txt

# Specify output format
python3 scripts/image_ocr.py /path/to/image.jpg --format json
python3 scripts/image_ocr.py /path/to/image.jpg --format markdown

PDF OCR

# Convert PDF to Word (default)
python3 scripts/pdf_ocr.py document.pdf

# Convert PDF to Markdown
python3 scripts/pdf_ocr.py document.pdf --format markdown

# Convert PDF to JSON
python3 scripts/pdf_ocr.py document.pdf --format json

# From public URL
python3 scripts/pdf_ocr.py --pdf-url "https://example.com/doc.pdf" --format word

Setup

API Credentials

Get credentials from iFlytek Open Platform:

For Image OCR:

• APP_ID: Application ID
• API_KEY: API key for authentication
• API_SECRET: API secret for signing requests

For PDF OCR:

• APP_ID: Application ID
• API_SECRET: Application secret (for signature generation)

Environment Variables

# Required for both Image OCR and PDF OCR
export IFLY_APP_ID="your_app_id"

# Required for Image OCR
export IFLY_API_KEY="your_api_key"

# Required for PDF OCR
export IFLY_API_SECRET="your_api_secret"

Features

Image OCR (LLM OCR)

• AI-powered: Advanced LLM-based OCR for high accuracy
• Multi-format output: JSON, Markdown, or both
• Layout understanding: Preserves document structure
• Multi-language: Supports text extraction in multiple languages
• Image preprocessing: Automatic rotation correction, noise removal

PDF OCR

• AI-powered OCR: Advanced AI model for accurate text extraction
• Multiple output formats:
  • Word (.docx) - Editable Word document
  • Markdown - Plain text with formatting
  • JSON - Structured data
• Large PDF support: Up to 100 pages per document
• Page-by-page results: Access individual page results
• Download URLs: Direct links to processed files

API Parameters

Image OCR Parameters

Parameter	Type	Required	Description
image_path	string	Yes	Path to image file
--format	string	No	Output format: json, markdown, json,markdown (default: json,markdown)
--output	string	No	Save result to file

PDF OCR Parameters

Parameter	Type	Required	Description
pdf_path	string	Yes*	Path to PDF file
--pdf-url	string	No*	Public URL of PDF file
--format	string	No	Output format: word, markdown, json (default: word)
--no-poll	flag	No	Return task ID without polling
--poll-interval	int	No	Polling interval in seconds (min 5, default: 5)
--max-wait	int	No	Maximum wait time in seconds (default: 300)

*Either pdf_path or --pdf-url must be provided

Authentication

Image OCR (HMAC-SHA256)

Uses HMAC-SHA256 signature authentication:

1. Generate RFC1123 format date: EEE, dd MMM yyyy HH:mm:ss GMT
2. Create signature origin: host: {host}\\ndate: {date}\\nPOST {path} HTTP/1.1
3. Calculate signature: HMAC-SHA256(signature_origin, apiSecret)
4. Build authorization: hmac username="{apiKey}", algorithm="hmac-sha256", headers="host date request-line", signature="{signature}"
5. Encode authorization in base64
6. Send as query parameters: ?authorization={auth}&host={host}&date={date}

PDF OCR (MD5 + HMAC-SHA1)

Uses MD5 + HMAC-SHA1 signature authentication:

1. Generate timestamp (Unix epoch in seconds)
2. Calculate auth = MD5(appId + timestamp)
3. Calculate signature = Base64(HMAC-SHA1(auth, apiSecret))
4. Send headers:
   • appId: Application ID
   • timestamp: Timestamp in seconds
   • signature: Generated signature

Important: Timestamp must be within 5 minutes of server time.

Response Format

Image OCR Response

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

PDF OCR Start Response

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

PDF OCR Status Response

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

Task Status (PDF OCR)

Status	Description
CREATE	Task created successfully
WAITING	Waiting in queue
DOING	Processing
FINISH	Completed
FAILED	Failed
ANY_FAILED	Partially completed (some pages failed)
STOP	Paused

Error Codes

(｡･ω･｡) 嗨遇到错误码了吗？来看看怎么解决吧 ✧⁺⸜(●˙▾˙●)⸝⁺✧

Platform Common Error Codes

Code	Description	Hint	Solution
10009	input invalid data	(◎_◎;) 哎呀~数据格式不太对呢	检查输入数据是否符合要求
10010	service license not enough	(╯°□°)╯︵ ┻━┻ 授权数量不足或已过期！	提交工单联系客服
10019	service read buffer timeout	(。-`ω´-) session超时啦~	检查是否数据发送完毕但未关闭连接
10043	Syscall AudioCodingDecode error	(◎_◎;) 音频解码失败惹...	检查aue参数，如果为speex，请确保音频是speex音频并分段压缩且与帧大小一致
10114	session timeout	(。-`ω´-) 会话时间超时啦~	检查是否发送数据时间超过了60s
10139	invalid param	(◎_◎;) 参数好像不太对呢	检查参数是否正确
10160	parse request json error	(◎_◎;) 请求数据格式有误~	检查请求数据是否是合法的json
10161	parse base64 string error	(◎_◎;) Base64解码失败啦	检查发送的数据是否使用base64编码了
10163	param validate error	(◎_◎;) 参数校验没通过呢	具体原因见详细的描述
10200	read data timeout	(。-`ω´-) 读取数据超时了~	检查是否累计10s未发送数据并且未关闭连接
10222	context deadline exceeded	(╯°□°)╯︵ ┻━┻ 出错啦！	1.检查上传数据是否超过接口上限；2.SSL证书无效请提交工单
10223	RemoteLB: can't find valued addr	(◎_◎;) 找不到服务节点呢	提交工单联系技术人员
10313	invalid appid	(◎_◎;) appid和apikey不匹配哦	检查appid是否合法
10317	invalid version	(◎_◎;) 版本号有问题呢	请到控制台提交工单联系技术人员
10700	not authority	(╯°□°)╯︵ ┻━┻ 权限不足！	按照报错原因对照开发文档检查，如仍无法解决，请提供sid及错误信息提交工单
11200	auth no license	(╯°□°)╯︵ ┻━┻ 功能未授权！	检查appid是否正确，确认是否添加了相关服务，检查调用量是否超限或授权是否到期
11201	auth no enough license	(╯°□°)╯︵ ┻━┻ 每日交互次数超限啦！	提交应用审核提额或联系商务购买企业级接口
11503	server error: atmos return error	(。-`ω´-) 服务器返回了错误数据...	提交工单
11502	server error: too many datas	(。-`ω´-) 服务器配置有问题呢	提交工单
100001~100010	WrapperInitErr	(◎_◎;) 引擎调用出错啦！	请根据message中的errno查看引擎错误码说明

Additional Resources

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

---

Original API Error Codes

Code	Description	Solution
10000	System error	Check auth info, request method, parameters
10001	Signature authentication failed	Check credentials
10002	Business processing error	Check error message
10003	Quota/insufficient balance	Check account balance

Limitations

Image OCR

• Format: Common image formats (JPG, PNG, etc.)
• Size: Reasonable file sizes for web upload
• Rate limiting: Follow API rate limits

PDF OCR

• Max pages: 100 pages per PDF
• Protected PDFs: Not supported (password/encrypted)
• Rate limiting: Status query limited to once per 5 seconds
• Time limit: Timestamp must be within ±5 minutes of server time

Tips

Image OCR

1. High-quality images: Use clear, high-resolution images for best results
2. Multiple formats: Use json,markdown to get both structured and formatted output
3. Save results: Use -o flag to save OCR results to file

PDF OCR

1. Math formulas: Use markdown format for PDFs with mathematical formulas
2. Large PDFs: Split into sections if > 100 pages
3. Polling interval: Minimum 5 seconds between status queries
4. Network URLs: Ensure PDF URLs are publicly accessible
5. Download URLs: Download files promptly as URLs may expire