zai-ocr-skill

What I do

I provide the exact recipe for an agent to extract text with layout structure from an image or PDF via the Z.AI GLM-OCR layout_parsing API. Unlike a vision-chat description, the dedicated endpoint returns the document's text organized by detected layout (blocks, reading order, tables).

Why a skill (not vision chat)

• POST /layout_parsing is a dedicated document-extraction endpoint — richer and more faithful for dense/structured documents than asking a chat model to describe an image.
• Input is an http(s) URL. Base64 is documented in the API schema but every base64 form is rejected server-side with code 1214 (verified 2026-08-30: png/jpeg/pdf × raw/data-URI/padded/unpadded) — local files use the vision fallback in Path B.

Prerequisite — API key resolution

KEY="${ZAI_API_KEY:-$(jq -r '.["zai"].key // .["zai-coding-plan"].key // empty' \
     ~/.local/share/opencode/auth.json 2>/dev/null)}"
[ -z "$KEY" ] && { echo "ZAI_API_KEY not found — set it (export ZAI_API_KEY) or run \`opencode auth login\` (Z.AI)."; exit 1; }

If neither source has the key, stop and report — do not proceed.

Recipe

Path A — file already has a public URL (full layout result)

FILE_URL="https://example.com/document.png"           # REQUIRED — public http(s) URL, png/jpg/pdf
BASE="${ZAI_MEDIA_ENDPOINT:-https://api.z.ai/api/paas/v4}"  # pay-as-you-go ONLY

RESP=$(curl -sS --max-time 180 -X POST "$BASE/layout_parsing" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"model\":\"glm-ocr\",\"file\":\"$FILE_URL\"}")

printf '%s' "$RESP" | python3 -c '
import sys, json
d = json.load(sys.stdin)
if d.get("error"):
    sys.stderr.write("API error: " + json.dumps(d["error"]) + "\n"); sys.exit(1)
print(d.get("md_results") or "(empty md_results)")
for page in d.get("layout_details", []):
    for el in page:
        print("[" + str(el.get("label", "")) + "] " + str(el.get("content", "")))'

Output: md_results (markdown of the whole document) plus one [label] content line per layout element (text/table/formula/image) on stdout.