BaiduOCR-LocalFallback

> Disclaimer:

> 1. This project is not an official Baidu product and has no affiliation with Baidu. This project only provides a wrapper for Baidu OCR API; users must apply for a Baidu Cloud account and comply with Baidu's terms of service.

> 2. This project is 99% AI-generated. The AI's owner has no programming background. Please evaluate the project's feasibility before use.

115+ Baidu OCR API interfaces with EasyOCR local fallback — auto-switches to local recognition when the network is unstable.

Features

• ✅ 115+ OCR APIs - General, ID cards, receipts, documents, education, and more
• ✅ Local fallback - Integrates EasyOCR; auto-switches when Baidu OCR is unavailable
• ✅ Image preprocessing - Auto compresses and converts to fit the 4MB limit
• ✅ Token caching - access_token cached for 25 days
• ✅ Auto retry - Retries 3 times on network fluctuations
• ✅ Multiple config methods - Environment variables, config file, or interactive setup

Installation

One-click install

bash <(curl -s https://raw.githubusercontent.com/xx235300/BaiduOCR-LocalFallback/main/install.sh)

Manual install

# 1. Clone the repo
git clone https://github.com/xx235300/BaiduOCR-LocalFallback.git
cd BaiduOCR-LocalFallback

# 2. Install dependencies
pip3 install -r requirements.txt

# 3. Configure API credentials
python3 scripts/ocr.py --configure

Quick Start

from scripts.ocr import OCR

ocr = OCR()

# General text recognition
result = ocr.recognize(image="/path/to/image.jpg", api="general_basic")

# ID card recognition
result = ocr.recognize(image="/path/to/idcard.jpg", api="idcard", id_card_side="front")

# Handwriting (local fallback)
result = ocr.recognize(image="/path/to/handwriting.jpg", api="handwriting")

Supported APIs

General Text

ID & Cards

Receipts

Handwriting / Documents

More APIs (115+)

Run python3 scripts/ocr.py --show-apis for the full list.

Configuration

Method 1: Interactive

python3 scripts/ocr.py --configure

Method 2: Environment variables (recommended for security)

export BAIDU_OCR_API_KEY="<your_api_key>"
export BAIDU_OCR_SECRET_KEY="<your_secret_key>"

Method 3: Config file

mkdir -p ~/.openclaw/skills/BaiduOCR-LocalFallback
cat > ~/.openclaw/skills/BaiduOCR-LocalFallback/config.json << 'EOF'
{
  "api_key": "<your_api_key>",
  "secret_key": "<your_secret_key>"
}
EOF
chmod 600 ~/.openclaw/skills/BaiduOCR-LocalFallback/config.json

Response Format

{
  "words_result": [
    {"words": "Recognized text", "location": {"vertices": [{"x": 0, "y": 0}, ...]}}
  ],
  "words_result_num": 1,
  "fallback_info": {  // only present when using local fallback
    "engine": "EasyOCR",
    "message": "Baidu OCR unavailable, using local EasyOCR"
  }
}

Error Handling

from scripts.ocr import OCR
from scripts.baidu_client import BaiduOCRError

ocr = OCR()
try:
    result = ocr.recognize(image="/path/to/image.jpg")
except BaiduOCRError as e:
    print(f"Baidu OCR error: {e.error_code} - {e.error_msg}")
except Exception as e:
    print(f"Other error: {e}")

FAQ

Q: I have no coding experience, what should I do if an error occurs during use?

Just send the cloud document link to the AI and let it troubleshoot and find a solution on its own.

Sample prompt:

Please troubleshoot and resolve the issue according to the skill usage documentation.
Skill Usage Documentation: https://my.feishu.cn/docx/Gjy0djSado5YqVxzO6ecYbOmn4g?from=from_copylink

Q: How to get Baidu OCR API credentials?

1. Go to Baidu Cloud Console
2. Search "OCR" or "文字识别"
3. Create an app and enable the OCR services you need
4. Get API Key and Secret Key from "My Apps"

Q: "Baidu OCR call failed" but no auto-switch to local fallback?

Check if fallback is disabled:

ocr = OCR(use_fallback=False)  # Fallback disabled

Q: EasyOCR initialization is slow?

First run requires downloading models (~100MB). Pre-initialize:

from scripts.local_ocr import local_ocr
local_ocr._init_reader()  # Warm up

Q: How to handle Base64 images?

import base64

# Read image and convert to Base64
with open("image.jpg", "rb") as f:
    img_base64 = base64.b64encode(f.read()).decode()

result = ocr.recognize(image=img_base64, api="general_basic")

Q: How to specify output format?

# Table - returns Excel
result = ocr.recognize(image="table.jpg", api="table", request_type="excel")

# Table - returns JSON
result = ocr.recognize(image="table.jpg", api="table", request_type="json")

Q: Web image recognition failed?

Web images must be publicly accessible. Ensure:

1. Image URL is publicly reachable
2. Firewall allows outbound 80/443
3. Try downloading locally first

Q: How to disable SSL certificate verification (dev only)?

import os
os.environ['REQUESTS_CA_BUNDLE'] = '/path/to/ca-bundle.crt'

Performance Tips

• First-time EasyOCR requires downloading models (~100MB), please be patient
• Recommended image size under 2MB for best performance
• Large images are auto-compressed and scaled
• access_token is auto-cached and refreshed

Related Documents

Baidu Cloud Documentation Center

License

MIT © 2026 xx235300