SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillspdf-image-text-extractor

pdf-image-text-extractor

Design & creation

View repository

Updated 10-16 05:50

About this skill

PDF and image text extraction

Task objective

  • This Skill is used to: recognize and extract text content from images or PDF documents uploaded by the user
  • Capabilities include: image text detection, PDF text extraction,scanned OCR recognition、structured table extraction、batch directory processing, format preservation, Markdown file generation
  • Trigger conditions: the user uploads an image or PDF and requests text extraction, or asks about the text content in a document; the user needs to batch process a folder; the user needs to extract table data from a PDF

🔑 Authentication

This Skill is completely free, but requires configuring a RedFox API Key to request usage permission; the Key itself does not deduct credits.

Go to RedFox hub to register and obtain a personal API Key, and configure it through any of the following methods:

# 方式一：配置文件（如 OpenClaw 的 ~/.openclaw/openclaw.json）
{ "env": { "REDFOX_API_KEY": "ak_xxxx..." } }
Method 2: Terminal environment variables

export REDFOX_API_KEY="ak_xxxx..."


> ⚠️ **每次执行任何操作前，必须先运行 `python3 scripts/record.py`**。
> 若脚本以非零退出码终止（未配置 Key 或接口返回失败），则**立即停止执行**，并向用户提示：
> 「需要配置红狐 API Key 才能使用本 Skill。请前往 https://redfox.hk/settings/api-keys?source=github **免费**注册获取，然后配置环境变量：`export REDFOX_API_KEY="ak_xxxx..."`」

## 前置准备

### 必要依赖

pymupdf>=1.23.0 requests>=2.28.0


```bash
pip install pymupdf>=1.23.0 requests>=2.28.0

Zero extra dependency notes

This Skill requires no installation of any OCR engine or table library：

  • Scanned PDFs: automatically rendered as high-definition PNGs and handed to the Agent's read_image(AI vision) for recognition
  • Table extraction: uses pymupdf's built-in find_tables(), no pdfplumber needed
  • Only pymupdf + requests two packages are needed to enable all features

Supported file formats

  • Image formats: PNG, JPG, JPEG, GIF, WebP, BMP, TIFF
  • Document formats: PDF (text-based + scanned; scanned versions are automatically rendered as images for AI recognition)

Operation steps

Standard process

Step 0: Authentication check (must be performed first)

python3 scripts/record.py
  • Output ✅ 鉴权通过，已获得使用权限 → continue with the subsequent process
  • The script terminates with a non-zero exit code → stop immediately, show the user the error message output by the script, and inform them that they need to go to RedFox hub to obtain an API Key for free

Step 0.5: Version update prompt (on every execution)

python3 scripts/changelog.py
  • If there is output (first use or version upgrade) → display the output contentin full to the user, then continue
  • If there is no output (the version is already the latest) → continue directly

Image text extraction process

  1. Receive image

    • Confirm that the user has uploaded an image file
    • Obtain the access URL of the image

  2. Recognize image content (first round: global recognition)

    • Use the read_image tool to recognize image content
    • In the prompt, explicitly require recognition of all text content, including titles, body text, annotations, watermarks, etc.
    • For numeric characters, pay special attention to visual shape features (number of closed loops, direction of openings, curve direction) to ensure accurate recognition of easily confused digits such as 6/8/9/0/3

  3. Determine whether text exists

    • If text is detected: proceed to step 4
    • If no text is detected: inform the user that "the image does not contain extractable text", and the task ends

  4. Extract and organize the text

    • Extract all text content from the image
    • Preserve the original structure and layout
    • Organize into an easy-to-read format

  5. Secondary focused verification of numbers (executed silently, not shown to the user)

    • ⚠️ Important: The entire verification process (including shape descriptions, comparison tables, verification rounds, etc.) must be executed silently. It is forbidden to display any part of the verification process in the conversation output; only show the user the final confirmed extraction result
    • For all numeric strings in the first-round extraction results (phone numbers, order numbers, amounts, dates, etc.), perform secondary focused recognition:
    • Strategy A: Local zoom verification
      • Use read_imageagain, but this time in the prompt only require recognition of the specific numeric string region
      • Prompt template: "Please focus only on the numeric string [context description] in the image, describe the visual shape of each numeric character digit by digit (how many closed loops, the direction of openings, the direction of curves), then give the final judgment result"
    • Strategy B: Cross-validation
      • Compare the shape description from the first round with the independent judgment from the second round
      • If the two rounds agree → confirm as the final result
      • If the two rounds disagree → mark [待确认：第一轮识别为X，第二轮识别为Y]
    • Quick reference table for easily confused digit pairs：
      Digit Key visual features
      8 Two closed loops, one above the other, like a snowman/hourglass
      6 Only one closed loop at the bottom, with an arc curving to the left at the top
      9 Only one closed loop at the top, with a vertical line extending downward at the bottom
      0 A complete closed ellipse with no opening
      3 Open on the right side, with two arcs facing right
      5 A horizontal line at the top + a vertical line on the left + an arc at the bottom
      S Similar to 5 but vertically symmetrical, with no horizontal line
      O A closed shape rounder than 0

PDF text extraction process

  1. Receive the PDF file

    • Confirm that the user has uploaded a PDF file
    • Obtain the local path of the PDF file

  2. Call the script to extract text

    # 标准模式（自动检测扫描页渲染为图片 + 提取表格）
python3 scripts/pdf_text_extractor.py <pdf_file_path>

# 仅提取文字，跳过表格（速度更快）
python3 scripts/pdf_text_extractor.py <pdf_file_path> --no-tables

# 不渲染扫描页（仅提示哪些页是扫描页）
python3 scripts/pdf_text_extractor.py <pdf_file_path> --no-render

# 自定义扫描页图片输出目录 / 渲染分辨率
python3 scripts/pdf_text_extractor.py <pdf_file_path> --scan-dir ./ocr_pages --dpi 300

  3. Process the extraction results

    The script returns JSON; key field descriptions:

    Field Description
    success Whether extraction succeeded
    text Markdown-format body text (text layer)
    page_count Total number of pages
    tables_markdown Markdown summary of all tables
    ocr_images Images that require Agent read_image recognition list [{'page','image'}]
    warnings Non-fatal warnings (such as scanned page prompts, etc.)
    • If success=true: proceed to step 4
    • If success=false: inform the user of the contents of the error field, and the task ends

  4. Formatted output

    • Display the contents of the text field
    • If tables_markdown is non-empty, display the table contents separately
    • If ocr_images is non-empty: use read_image Recognize these images, merge the recognition results into the main text, and inform the user which pages are scanned pages
    • If warnings is non-empty, show a warning message to the user

Batch processing workflow

When the user provides a directory path, or requests batch processing of multiple files:

  1. Confirm the directory path

    • Obtain the directory path specified by the user

  2. Call the batch extraction script

    # 输出合并 Markdown 到终端
python3 scripts/batch_extractor.py <目录路径>

# 保存到文件
python3 scripts/batch_extractor.py <目录路径> -o result.md

# 输出 JSON 结构化数据
python3 scripts/batch_extractor.py <目录路径> --json

# 不渲染扫描页 / 自定义扫描页输出目录
python3 scripts/batch_extractor.py <目录路径> --no-render --scan-dir ./ocr_pages

  3. Processing results

    • The script outputs progress information to stderr and results to stdout
    • If -ois specified, inform the user of the file save location
    • Display summary statistics (total files / successes / failures)
    • If the user requests to view the content, display combined_markdown or the extraction results of each file

Unified output steps

  1. Generate output results
    • Generate a Markdown file according to the user's needs
    • Include information such as file source, extraction status, and text content
    • Organize the content using clear headings and structure

Optional branches

  • When the user only needs to view the text content: output the text directly without generating a file
  • When the user requests to save the results: generate .md file
  • When the text in images/PDFs is blurry or difficult to recognize: explain the situation and provide the best recognition result
  • When the PDF is a scanned version: the script has automatically rendered it as images, and the Agent can use read_image to recognize them one by one, without any OCR dependency
  • When the user requests table extraction: use standard mode (table extraction is included by default), and display the tables_markdown field
  • When the user requests batch processing: use batch_extractor.py, which supports mixed directories of PDFs + images

Resource index

  • Authentication script：scripts/record.py
    • Purpose: call https://redfox.hk/story/api/skill/record/save to request usage permission and complete authentication verification at the same time
    • Failure behavior: terminate with exit code 1 when the Key is not configured or the API returns 3106/3107
  • Version prompt script：scripts/changelog.py
    • Purpose: display new feature introductions on first use or version upgrade, and exit silently when the version is the same
    • Version record file:~/.pdf_image_extractor_version
  • PDF extraction script：scripts/pdf_text_extractor.py
    • Purpose: extract text from PDFs + structured table extraction + render scanned pages as images (for read_image)
    • Parameters:<pdf_path> [--no-tables] [--no-render] [--scan-dir DIR] [--threshold N] [--dpi N]
    • Output: JSON, including text / tables_markdown / ocr_images / warnings and other fields
  • Batch extraction script：scripts/batch_extractor.py
    • Purpose: batch process all PDF + image files in a directory
    • Parameters:<目录路径> [--no-tables] [--no-render] [--scan-dir DIR] [-o FILE] [--json]
    • Output: merged Markdown report or JSON structured data

Notes

Image text extraction

  • Recognition accuracy: text recognition results are affected by factors such as image clarity, font, and background, and errors may exist
  • The principle of "look at the shape first, then judge the number": when recognizing numbers, you must first describe the visual shape features of the character (number of closed circles, opening direction, curve direction), and then judge the number based on the features; it is forbidden to skip the shape description and directly output the number
  • Dual recognition of key number strings: For key numeric strings such as mobile phone numbers, ID card numbers, bank card numbers, order numbers, etc., two rounds of recognition (global recognition + focused verification) must be performed; if the two rounds are inconsistent, mark as pending confirmation
  • The verification process is executed silently: Process information such as the shape description, comparison table, and round records of the numeric secondary verification must strictly not be shown to the user; it is only executed silently in the background, and only the confirmed extraction result is ultimately output
  • Uncertainty marking: For characters that cannot be 100% confirmed, use [?] to mark and provide 2 alternatives, such as 158****8[?可能为6]624
  • Text layout: When extracting, try to maintain the text structure and order of the original image
  • Multilingual support: Supports recognition of text in multiple languages such as Chinese and English

PDF text extraction

  • Format preservation: The script will try to preserve the paragraph structure and heading hierarchy of the original text
  • Scanned PDF: Automatically detects pages with sparse text layers (< 20 characters) and renders them as high-definition PNGs, handing them to read_image(AI vision) for recognition, without requiring any OCR engine; recognition accuracy depends on AI vision capability
  • Table extraction: Enabled by default; use pymupdf find_tables() to recognize tables and output in Markdown format; recognition of complex tables (merged cells, nested tables) may be poor
  • Encrypted PDF: Encrypted or password-protected PDF files are not supported

Batch processing

  • File sorting: Process in alphabetical order by file name
  • Image recognition: In batch mode, images are not locally OCRed; they are uniformly collected into ocr_images list, and the Agent calls read_image one by one for recognition
  • Large directories: It is recommended to process no more than 100 files at a time; too many files may cause long processing time
  • Output method: By default, output to the terminal; it is recommended to specify -o result.md to save as a file

General precautions

  • Privacy protection: Processed files will not be stored and are only used in the current session
  • File size: It is recommended to process files smaller than 50MB; overly large files may cause slow processing

Usage examples

Example 1: Image text extraction

User action: Upload an image containing text

Agent processing：

  1. Execute python3 scripts/record.py → ✅ 鉴权通过
  2. Execute python3 scripts/changelog.py → if there is output, show it to the user
  3. Use read_image tool to recognize the image
  4. Extracted text content: "All the entanglements experienced / and the sorrowful regrets / cannot be meaningless"
  5. Directly output the extraction result

Example 2: PDF text extraction + table

User action: Upload a PDF and request "extract the text of this PDF"

Agent processing：

  1. Execute python3 scripts/record.py → authentication passed
  2. Execute python3 scripts/changelog.py → silent
  3. Execute:python3 scripts/pdf_text_extractor.py ./document.pdf
  4. Get JSON result:text(main text) + tables_markdown(table)
  5. Display the main text and table content separately, generate ./extracted_from_pdf.md

Example 3: Scanned PDF (render + AI recognition)

User action: Upload scanned PDF

Agent processing：

  1. Authentication + version check
  2. Execute:python3 scripts/pdf_text_extractor.py ./scan.pdf
  3. The script detects pages with an empty text layer and renders them as high-resolution PNGs,ocr_images and provides the image path
  4. The Agent uses read_image to recognize these PNGs one by one and extract the text
  5. Inform the user: "Pages 1/2/3 are scanned pages and have been recognized via AI vision," and display the extracted results

Example 4: Batch process a directory

User action: "Help me extract the text from all files in the ./documents/ folder"

Agent processing：

  1. Authentication + version check
  2. Execute:python3 scripts/batch_extractor.py ./documents/ -o batch_result.md
  3. The script processes all PDFs + images in the directory and outputs progress to stderr
  4. Inform the user: "Processed 8 files (7 succeeded / 1 failed); results have been saved to batch_result.md"
  5. Display summary statistics

Example 5: Handling when no API Key is configured

User action: Upload an image and request text extraction, but no REDFOX_API_KEY

Agent processing：

  1. Execute python3 scripts/record.py → the script errors out and exits
  2. Stop immediately, and output to the user: "You need to configure a RedFox API Key to use this Skill. Please go to https://redfox.hk/settings/api-keys?source=github to register for freeand obtain one, then execute:export REDFOX_API_KEY="ak_xxxx..."」