Paddleocr Text Recognition

PaddleOCR Text Recognition Skill

When to Use This Skill

Trigger keywords (routing): Bilingual trigger terms (Chinese and English) are listed in the YAML description above—use that field for discovery and routing.

Use this skill for:

• Extract text from images (screenshots, photos, scans)
• Extract text from PDFs or document images when the goal is line/box-level text, not recovering table grids, formulas, or full reading-order layout
• Extract text from URLs or local files that point to images/PDFs

Do not use for:

• Plain text files, code files, or markdown documents that can be read directly as text
• Documents with tables, formulas, charts, or complex layouts — use Document Parsing instead
• Tasks that do not involve image-to-text conversion

Installation

Scripts declare their dependencies inline (PEP 723). No separate install step is needed — uv resolves dependencies automatically:

uv run scripts/ocr_caller.py --help

How to Use This Skill

Working directory: All uv run scripts/... commands below should be run from this skill's root directory (the directory containing this SKILL.md file).

Basic Workflow

1. Identify the input source:

• User provides URL: Use the --file-url parameter
• User provides local file path: Use the --file-path parameter

1. Execute OCR:

   uv run scripts/ocr_caller.py --file-url "URL provided by user" --pretty

Or for local files:

   uv run scripts/ocr_caller.py --file-path "file path" --pretty

Performance note: Parsing time scales with document complexity. Single-page images typically complete in 1-3 seconds; large PDFs (50+ pages) may take several minutes. Allow adequate time before assuming a timeout.

Default behavior: save raw JSON to a temp file:

• If --output is omitted, the script saves automatically under the system temp directory
• Default path pattern: <system-temp>/paddleocr/text-recognition/results/result_<timestamp>_<id>.json
• If --output is provided, it overrides the default temp-file destination
• If --stdout is provided, JSON is printed to stdout and no file is saved
• In save mode, the script prints the absolute saved path on stderr: Result saved to: /absolute/path/...
• In default/custom save mode, read and parse the saved JSON file before responding
• Use --stdout only when you explicitly want to skip file persistence

1. Parse JSON response:

• In default/custom save mode, load JSON from the saved file path shown by the script
• Check the ok field: true means success, false means error
• Extract text: text field contains all recognized text
• If --stdout is used, parse the stdout JSON directly
• Handle errors: If ok is false, display error.message

1. Present results to user:

• Display extracted text in a readable format
• If the text is empty, the image may contain no text
• In save mode, always tell the user the saved file path and that full raw JSON is available there

What to Do After Extraction

Common next steps once you have the recognized text:

• Save to file: Write the text field to a .txt or .md file
• Search the content: Search the saved output file for keywords
• Feed to another pipeline: The text field is clean plain text, ready for downstream processing
• Poor results: See "Tips for Better Results" below before retrying

Complete Output Display

Always display the COMPLETE recognized text to the user. The user typically needs the full content for downstream use — truncation silently loses data they may not notice is missing.

• Display the entire text field, no matter how long
• Do not use phrases like "Here's a summary" or "The text begins with..."
• Do not truncate with "..." unless the text truly exceeds reasonable display limits (>10,000 chars)

Example - Correct:

User: "Extract the text from this image"
Agent: I've extracted the text from the image. Here's the complete content:

[Display the entire text here]

Example - Incorrect:

User: "Extract the text from this image"
Agent: I found some text in the image. Here's a preview:
"The quick brown fox..." (truncated)

Understanding the Output

The script returns a JSON envelope with ok, text, result, and error fields. Use text for the recognized content; result contains the raw API response for debugging.

For the full schema and field-level details, see references/output_schema.md.

Raw result location (default): the temp-file path printed by the script on stderr

Alternative: paddleocr CLI

This mirror keeps the bundled scripts/ocr_caller.py as the default path. The upstream PaddleOCR project (since PR #18090, 2026-06-03) also ships an official CLI that calls the same API directly. If the paddleocr package is installed, you can use it as a drop-in alternative — no uv run or local scripts required.

Install (one-time):

pip install "paddleocr>=3.7.0"

Environment: the CLI only needs PADDLEOCR_ACCESS_TOKEN. It resolves the API endpoint internally, so PADDLEOCR_OCR_API_URL is not required when using the CLI (the URL is still required by the script).

Basic OCR:

# From URL
paddleocr api --model_type ocr --file_url "https://example.com/image.png"

# From local file
paddleocr api --model_type ocr --file_path "./document.pdf"

Common options:

# Specific model
paddleocr api --model_type ocr --model PP-OCRv5 --file_path "./report.pdf"

# Disable preprocessing (faster, for flat/well-oriented images)
paddleocr api --model_type ocr --file_path "./document.pdf" \
  --use_doc_unwarping False --use_doc_orientation_classify False

# Page ranges
paddleocr api --model_type ocr --file_path "./large.pdf" --page_ranges "1-5,10,15-20"

# Save result to file
paddleocr api --model_type ocr --file_url "https://..." --output result.json

CLI output format — different from the script envelope:

{
  "jobId": "job-xxx",
  "pages": [
    {
      "prunedResult": {
        "rec_texts": ["Line 1", "Line 2"],
        "rec_scores": [0.98, 0.95]
      },
      "ocrImageUrl": "https://..."
    }
  ]
}

The CLI prints {jobId, pages:[...]} to stdout. It does not wrap the response in the script's {ok, text, result, error} envelope, does not auto-save to a temp file, and does not concatenate text for you. If you switch paths, update your parsing logic accordingly.

Scripts vs CLI — at a glance:

Run paddleocr api --help for the full option list.

Usage Examples

Example 1: URL OCR

uv run scripts/ocr_caller.py --file-url "https://example.com/invoice.jpg" --pretty

Example 2: Local File OCR

uv run scripts/ocr_caller.py --file-path "./document.pdf" --pretty

Example 3: OCR With Explicit File Type

uv run scripts/ocr_caller.py --file-url "https://example.com/input" --file-type 1 --pretty

• --file-type 0: PDF
• --file-type 1: image