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

PDF OCR Parameters

*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}\\ date: {date}\\ POST {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)

Error Codes

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

Platform Common Error Codes

Additional Resources

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

Original API Error Codes

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