OpenParser Docs

Parse and extract requests reference model IDs in their configuration. Discover available models before you send work — unknown IDs return 422 with unsupported_ocr_model or unsupported_llm_model.

Hosted OCR model ids and per-model ocr_options keys are API and SDK surface — they are not exported from @openparser/schema or @openparser/adapters. Use runtime discovery (GET /models/ocr) for pricing, guidance, and availability; use the SDK helpers below for compile-time model and option checking.

Typed hosted helpers (SDK)

The TypeScript and Python SDKs ship generated helpers that mirror the current hosted OCR catalog. They do not replace GET /models/ocr for pricing or availability, but they give you literal model ids and option types at compile time.

TypeScript (@openparser/sdk):

import {
  HOSTED_OCR_MODEL_IDS,
  DEFAULT_HOSTED_OCR_MODEL_ID,
  hostedParseRequest,
  type HostedOcrModelId,
  type HostedOcrOptionsFor,
} from '@openparser/sdk';

// Literal union of ids the current SDK was generated against
const ids: readonly HostedOcrModelId[] = HOSTED_OCR_MODEL_IDS;

// Model-specific ocr_options typing
type PaddleOpts = HostedOcrOptionsFor<'paddleocr-vl-1.6'>;

// Build a parse body with checked options; wire API still accepts any string ocr_model
const body = hostedParseRequest({
  ocr_model: DEFAULT_HOSTED_OCR_MODEL_ID,
  output_format: 'openparser@1',
  ocr_options: { image_block_ocr: true },
});

await client.parse.sync(body, file);

hostedParseRequest is an identity helper — it preserves model-specific ocr_options checking. The HTTP ocr_model field remains string, so future models work before you bump the SDK.

Python (openparser on PyPI):

from openparser import (
    HOSTED_OCR_MODEL_IDS,
    DEFAULT_HOSTED_OCR_MODEL_ID,
    hosted_parse_request,
)

assert "paddleocr-vl-1.6" in HOSTED_OCR_MODEL_IDS

body = hosted_parse_request(
    DEFAULT_HOSTED_OCR_MODEL_ID,
    output_format="openparser@1",
    ocr_options={"image_block_ocr": True},
)

parsed = client.parse.sync(body, file=path)

Python exposes per-model option TypedDicts (for example PaddleocrVl16Options) via openparser.hosted_models for finer typing than a single HostedOcrOptionsFor alias.

Provider-native option Zod schemas for direct cloud calls live in @openparser/adapters — see adapters overview.

OCR models

GET /models/ocr returns the public OCR registry. Each entry includes capabilities, supported ocr_options, customer retail page pricing, and availability.

Set ocr_model on parse and file-backed extract requests to an id from this list. The current default is paddleocr-vl-1.6.

curl -s 'https://api.openparser.dev/models/ocr' \
  -H 'Authorization: Bearer YOUR_API_KEY'

openparser models ocr --json

const ocrModels = await client.models.ocr();

ocr_models = client.models.list_ocr()

Example response:

{
  "data": [
    {
      "id": "paddleocr-vl-1.6",
      "label": "PaddleOCR-VL 1.6",
      "is_default": true,
      "provider": {
        "key": "unknown",
        "label": "Baidu",
        "logo": "baidu",
        "logo_data": {
          "title": "Baidu",
          "view_box": "0 0 24 24",
          "paths": [
            { "d": "M9.154 0C7.71 0 6.54 1.658..." }
          ]
        }
      },
      "guidance": {
        "summary": "Fast default OCR for general documents.",
        "best_for": "Invoices, forms, and everyday PDFs.",
        "trade_off": "Less specialized than cloud document engines.",
        "output": "Markdown with layout regions."
      },
      "benchmark": {
        "score": 92.1,
        "version": "OmniDocBench v1.5",
        "qualification": "Overall score on the public OmniDocBench suite.",
        "source_url": "https://example.com/benchmark"
      },
      "output_summary": "Markdown + boxes",
      "capabilities": {
        "parse": true,
        "extract_source": true,
        "markdown": true,
        "regions": true,
        "options": {
          "image_block_ocr": true,
          "chart_recognition": true,
          "merge_layout_blocks": true
        }
      },
      "option_defaults": {
        "image_block_ocr": false,
        "chart_recognition": false,
        "merge_layout_blocks": false
      },
      "option_controls": [
        {
          "key": "image_block_ocr",
          "label": "Image block OCR",
          "summary": "OCR text inside detected image blocks.",
          "kind": "boolean"
        },
        {
          "key": "chart_recognition",
          "label": "Chart recognition",
          "summary": "Parse chart structure when present.",
          "kind": "boolean"
        },
        {
          "key": "merge_layout_blocks",
          "label": "Merge layout blocks",
          "summary": "Merge adjacent layout blocks into larger regions.",
          "kind": "boolean"
        }
      ],
      "pricing": {
        "usd_per_page": 0.001,
        "basis": "customer_retail",
        "configurations": [
          {
            "label": "Image block OCR",
            "usd_per_page": 0.0015,
            "options": { "image_block_ocr": true }
          }
        ]
      },
      "availability": "available"
    }
  ]
}

provider.logo is a stable, lightweight provider identifier. provider.logo_data contains portable SVG geometry owned by the OpenParser catalog. Render it with the supplied view_box and paths (using the current text color as fill) instead of maintaining a separate provider-logo mapping in your client. The path records may also include clip_rule and fill_opacity.

benchmark may be null when a model has no public score. pricing.configurations is omitted when page price does not vary with options; when present, each row is an exact retail total to match — do not sum deltas.

LLM models

GET /models/llm returns compatible extraction models with customer retail token pricing, certification flags for grounding and schema suggestion, and reasoning metadata.

Default mode=suggested returns a short recommended subset. Use this mode when picking a model for ordinary extract requests.

curl -s 'https://api.openparser.dev/models/llm' \
  -H 'Authorization: Bearer YOUR_API_KEY'

openparser models llm --json

const llmModels = await client.models.llm();

llm_models = client.models.list_llm()

Suggested responses include catalog metadata and pagination fields (page, limit, total, has_more). Each entry exposes id, label, provider, recommendation, certified_grounding, certified_suggest, and pricing in USD per 1M tokens.

Set llm_model on extract requests to an id from this catalog. Any compatible model can perform ordinary extraction; field grounding and schema suggestion require certified models.

Search the LLM catalog

mode=search returns the full compatible catalog. Filter with q (case-insensitive match against id, label, and provider) and paginate with page and limit.

curl -s 'https://api.openparser.dev/models/llm?mode=search&q=gpt&page=1&limit=50' \
  -H 'Authorization: Bearer YOUR_API_KEY'

openparser models llm --mode search --q gpt --page 1 --limit 50 --json

const results = await client.models.llm({ mode: 'search', q: 'gpt', page: 1, limit: 50 });

results = client.models.list_llm(mode="search", q="gpt", page=1, limit=50)

Use search when you need a specific provider or model family, or when building a model picker in your application. Current customer rates are always published through this endpoint.

Parsing — choose OCR models and options for parse requests
Extraction — choose LLM models for schema-constrained extract
openparser@1 schema — parse result shape (not model ids)
Errors and retries — unsupported_ocr_model and unsupported_llm_model

Model catalogs

Typed hosted helpers (SDK)

OCR models

LLM models

Search the LLM catalog

On this page

Model catalogs

Typed hosted helpers (SDK)

OCR models

LLM models

Search the LLM catalog

Related

On this page