Trigger when: (1) User wants to extract text, tables, formulas, or structured data from images/PDFs/scanned documents, (2) User mentions "OCR", "文字识别", "文档解析", (3) User has a document (screenshot, scanned page, invoice, paper, whiteboard photo) and needs its content in structured form, (4) User asks to parse, digitize, or extract content from a visual document.
Invokes the GLM-OCR SDK (pip install glmocr) to parse documents via Zhipu's cloud API. No GPU required. Returns structured JSON (regions with labels + bounding boxes) and Markdown. Agent can operate entirely via CLI — no YAML files needed.
NOT for: real-time camera feeds, audio transcription, or non-document images (photos, illustrations).
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Trigger when: (1) User wants to extract text, tables, formulas, or structured data from images/PDFs/scanned documents, (2) User mentions "OCR", "文字识别", "文档解析", (3) User has a document (screenshot, scanned page, invoice, paper, whiteboard photo) and needs its content in structured form, (4) User asks to parse, digitize, or extract content from a visual document.
Invokes the GLM-OCR SDK (pip install glmocr) to parse documents via Zhipu's cloud API. No GPU required. Returns structured JSON (regions with labels + bounding boxes) and Markdown. Agent can operate entirely via CLI — no YAML files needed.
NOT for: real-time camera feeds, audio transcription, or non-document images (photos, illustrations).
Parses documents (images, PDFs, scans) via the GLM-OCR SDK.
📌 On-demand: This skill requires only ZHIPU_API_KEY in the environment. No YAML config files or GPU needed.
⚡ Quick Start
# Install
pip install glmocr
# Set API key (once)export ZHIPU_API_KEY=sk-xxx
# or add to .env file in working directory:echo"ZHIPU_API_KEY=sk-xxx" >> .env
# One-linerimport glmocr
result = glmocr.parse()
(result.markdown_result)
(result.to_dict())
"document.pdf"
print
print
# CLI — pass API key directly (no env setup needed)
glmocr parse image.png --api-key sk-xxx
# Or load from a specific .env file
glmocr parse image.png --env-file /path/to/.env
# Or rely on env var / auto-discovered .env (set once, then omit)
glmocr parse image.png
glmocr parse ./scans/ --output ./output/ --stdout
Agents override everything via constructor kwargs or env vars — no YAML editing needed.
Key Environment Variables
Variable
Description
Example
ZHIPU_API_KEY
API key (required for MaaS)
sk-abc123
GLMOCR_MODEL
Model name
glm-ocr
GLMOCR_TIMEOUT
Request timeout (seconds)
600
GLMOCR_ENABLE_LAYOUT
Layout detection on/off
true
GLMOCR_LOG_LEVEL
DEBUG / INFO / WARNING / ERROR
INFO
Python API
Convenience function (single call)
import glmocr
# Single file → PipelineResult
result = glmocr.parse("invoice.png")
# Multiple files → list[PipelineResult]
results = glmocr.parse(["page1.png", "page2.png", "report.pdf"])
Class-based (multiple calls / resource reuse)
from glmocr import GlmOcr
parser = GlmOcr(api_key="sk-xxx") # mode auto-set to "maas"
parser = GlmOcr(mode="maas") # reads ZHIPU_API_KEY from env# Always use as context manager or call .close()with GlmOcr(api_key="sk-xxx") as parser:
result = parser.parse("document.png")
print(result.markdown_result)
parser.close() # if not using `with`
Constructor Parameters
Parameter
Type
Description
api_key
str
API key. Providing this auto-enables MaaS mode.
api_url
str
Override MaaS endpoint URL
model
str
Model name override
timeout
int
Request timeout in seconds (default: 600)
enable_layout
bool
Enable layout detection
log_level
str
Logging level
Working with PipelineResult
Fields
result.markdown_result # str — full document as Markdown
result.json_result # list[list[dict]] — structured regions per page
result.original_images # list[str] — absolute paths of input images
# Parse a single file → saves to ./output/<stem>/# MaaS mode is the default; ZHIPU_API_KEY must be set (or use --api-key)
glmocr parse image.png
# Pass API key directly without any env setup
glmocr parse image.png --api-key sk-xxx
# Parse a directory → saves each file to ./output/<stem>/
glmocr parse ./scans/
# Use self-hosted vLLM/SGLang instead of cloud
glmocr parse image.png --mode selfhosted
# Specify output directory
glmocr parse image.png --output ./results/
Read results in the terminal (agent-friendly)
# Print Markdown + JSON to stdout (and still save to disk)
glmocr parse image.png --stdout
# Print to stdout ONLY — do not write any files
glmocr parse image.png --stdout --no-save
# JSON only (no Markdown output)
glmocr parse image.png --stdout --json-only
# Pipe JSON into jq for structured extraction
glmocr parse image.png --stdout --json-only --no-save | jq '.[0] | map(select(.label=="table"))'
Save control
# Skip layout visualization images (faster, smaller output)
glmocr parse image.png --no-layout-vis
# Parse and save only JSON + Markdown, skip layout vis
glmocr parse image.png --no-layout-vis --output ./results/
Batch processing
# All images in a folder
glmocr parse ./invoice_scans/ --output ./parsed/ --no-layout-vis
# With progress visible in logs
glmocr parse ./docs/ --output ./parsed/ --log-level INFO
Debugging
glmocr parse image.png --log-level DEBUG
Full flag reference
Flag
Default
Description
--api-key / -k
env var
API key for MaaS mode (overrides ZHIPU_API_KEY)
--mode
maas
maas (cloud, default) or selfhosted (local GPU)
--env-file
auto
Path to .env file (default: auto-discover from cwd)
--output / -o
./output
Output directory
--stdout
off
Print JSON + Markdown to stdout
--no-save
off
Skip writing files (use with --stdout)
--json-only
off
stdout JSON only, no Markdown
--no-layout-vis
off
Skip layout visualization images
--config / -c
none
Path to YAML config override
--log-level
INFO
DEBUG / INFO / WARNING / ERROR
Typical Agent Workflow
receive document path / URL
│
▼
glmocr.parse(path) ← single call, handles PDF/image
│
▼
result.to_dict() ← safe to pass as tool output
│
├── markdown_result → hand to LLM for reading / summarization
└── json_result → structured extraction (tables, formulas, regions by label)
Filter by label
result = glmocr.parse("report.png")
regions = result.json_result[0] # first page
tables = [r for r in regions if r["label"] == "table"]
formulas = [r for r in regions if r["label"] == "formula"]
body_text = [r for r in regions if r["label"] == "text"]
Multi-page PDF → iterate pages
with GlmOcr(api_key="sk-xxx") as parser:
result = parser.parse("document.pdf") # all pages in one PipelineResultfor page_idx, page_regions inenumerate(result.json_result):
print(f"Page {page_idx + 1}: {len(page_regions)} regions")
for region in page_regions:
print(f" [{region['label']}] {region['content'][:60]}")
output_dir/
<image_stem>/
<image_stem>.json ← structured regions
<image_stem>.md ← full Markdown (with cropped figure images)
imgs/ ← cropped figures referenced in Markdown
layout_vis/ ← layout detection overlay images (if enabled)
<image_stem>.jpg
Common Pitfalls
ZHIPU_API_KEY not set: SDK defaults to MaaS mode. Without a key, parse() will fail with a clear error message and quick-fix instructions. Set via export ZHIPU_API_KEY=sk-xxx, add to a .env file, or pass --api-key sk-xxx to the CLI.
Large PDFs: Default timeout is 600s. For very long documents increase with timeout=1200.
result.json_result is a string: Happens when the model returns malformed JSON. The SDK preserves the raw string — parse or log it manually.
