---
name: sophnet-image-ocr
description: Use when the user needs to extract text, tables, or structured content from images or PDF files. Supports local files and URLs via Sophnet OCR API.
---

# Image / PDF OCR (Sophnet API)

Extract text and tables from images or PDF files using the Sophnet API. Returns Markdown-formatted output.

## Image Path Resolution

When users upload images via webchat or other channels, Moltbot saves them to `media/inbound/images/` in the workspace. The system prompt includes media understanding logs showing the resolved absolute path:

```
[Media Understanding] Resolved relative path: "media/inbound/images/xxx.jpg" -> "/absolute/path/to/workspace/media/inbound/images/xxx.jpg"
```

## Quick Start

```bash
uv run {baseDir}/scripts/ocr.py <image-or-pdf-path-or-url>
```

- **Image:** Converts local images to base64, calls OCR API, outputs Markdown.
- **PDF:** Renders each page to image, OCRs page by page, merges results with page markers. pymupdf is auto-installed from Aliyun mirror on first PDF use.

## Usage

```bash
# Local image
uv run {baseDir}/scripts/ocr.py /path/to/image.jpg

# Local PDF (multi-page supported)
uv run {baseDir}/scripts/ocr.py /path/to/document.pdf

# URL (image or PDF)
uv run {baseDir}/scripts/ocr.py https://example.com/image.jpg

# Custom model
uv run {baseDir}/scripts/ocr.py <image> --model PaddleOCR-VL-0.9B
```

Run `--help` for all available options.

## Agent Usage

When extracting text/tables from images or PDF for users:

1. Run `uv run {baseDir}/scripts/ocr.py <path-or-url>`
2. Capture stdout
3. Present extracted text/tables to the user
4. For Moltbot-uploaded images, check `media/inbound/images/` for the path

## Output Contract

- **Success:** Markdown-formatted text with tables (stdout)
- **Error:** Error message to stderr

## Common Errors

- `Unsupported file type: ...` — Ensure the file is a valid image format (PDF handled separately)
- `文件不存在` / download failure — Check path or URL accessibility
- `PDF 处理错误` — pymupdf auto-install may have failed; check network to Aliyun mirror
- **Request timeout** — Check network, script uses 60s timeout
- **Empty output** — Image may not contain readable text
- **Base64 conversion issues** — Verify local file path is correct and file exists

## API Details

See `{baseDir}/references/api-details.md` for endpoint, model, supported formats, and internal workflow.