Flexible Document OCR

This guide walks through running a document (PDF) through the VLM Run Gateway, from picking a model to handling the response. Document requests fan out one page at a time and default to ocr for pp-ocrv6. For a quick copy-paste example, see Quickstart. For the cost/latency/accuracy rationale behind picking a model, method, and DPI, see Why the Gateway.

1. Pick a model

Start with paddleocr/pp-ocrv6 for general-purpose PDF OCR. See Models for the full catalog and Methods if you need a specific operation like text detection (detect) instead of full OCR. zai-org/glm-ocr supports ocr and markdown output. rednote-hilab/dots.mocr adds layout parsing via parse_layout and parse_layout_only, plus ocr and markdown.

2. Send the document

Pass the PDF as a document_url content part. Prefer a hosted URL over a base64 data URI. See Multimodal Inputs for size limits and Method Parameters for document_dpi and other knobs.

from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.vlm.run/v1/openai",
    api_key="<VLMRUN_API_KEY>",
)

response = client.chat.completions.create(
    model="paddleocr/pp-ocrv6",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document_url",
                    "document_url": {"url": "https://example.com/invoice.pdf"},
                }
            ],
        }
    ],
    extra_body={"method": "ocr", "document_dpi": 72},
)

Request knobs

Field	Default	Notes
`document_dpi`	`72`	Rasterization DPI per page. See Method Parameters.
`document_max_pages`	`500`	Hard page cap. See Multimodal Inputs.
`method`	`ocr`	Per-page backend operation. See Methods.
`stream`	`false`	When true, emits ordered SSE page blocks. See Streaming vs non-streaming.

Document rasterization

When the request includes a document_url part, document_dpi controls the rasterization DPI for each page before OCR. Set it at the top level or inside method_params (either location works; if both are present, method_params wins).

DPI	Tradeoff
`72` (default)	Fast and cheap; fine for clean, standard-size text.
`150`	Good balance of legibility and per-page inference cost for denser pages.
`300`+	Preserves fine print and small text, at higher inference cost and latency per page.

Start at the default and only raise document_dpi if you see missed text on dense or small-font pages. Page count and file-size limits are documented under Multimodal Inputs.

3. Streaming vs non-streaming

Streaming is scoped to document requests today. Image-only and text-only requests do not support streaming on the VLM Run Gateway.

Mode	When to use
Non-streaming (default)	Short documents, batch pipelines, or when you need the full result before continuing.
Streaming (`stream: true`)	Long documents where you want to render or process pages as they finish.

Set stream: true to receive each page over SSE as it completes, in ascending page order, instead of waiting for the entire document:

stream = client.chat.completions.create(
    model="paddleocr/pp-ocrv6",
    stream=True,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "document_url", "document_url": {"url": "https://example.com/report.pdf"}}
            ],
        }
    ],
    extra_body={"method": "ocr", "document_dpi": 72},
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")

Each delta.content value is one component of the document structure: a <document> open or close tag, or a single <page> block, as described in the next section.

4. Parse the response

Each source document is returned as a <document> element that carries its metadata as attributes and wraps one <page> block per rasterized page:

<document filename="invoice.pdf" source_url="https://example.com/invoice.pdf" media_type="application/pdf" pages="1" dpi="72" bytes="120000">
<page index="0" dpi="72" width="612" height="792">
… page 0 markdown …
</page>
</document>

Multiple documents in one request

When a request includes more than one document_url (or file_url) content part, the response contains one <document> block per input, concatenated in request order:

<document filename="a.pdf" source_url="https://…/a.pdf" media_type="application/pdf" pages="1" dpi="72" bytes="120000">
<page index="0" dpi="72" width="612" height="792">
Page one text
</page>
</document>
<document filename="b.pdf" source_url="https://…/b.pdf" media_type="application/pdf" pages="2" dpi="72" bytes="240000">
<page index="0" dpi="72" width="612" height="792">
Section A
</page>
<page index="1" dpi="72" width="612" height="792">
Section B
</page>
</document>

Element attributes

Element	Attribute	Description
`<document>`	`filename`	Original file name of the source document.
`<document>`	`source_url`	URL the document was fetched from (omitted for base64 inputs).
`<document>`	`media_type`	MIME type of the source (e.g. `application/pdf`).
`<document>`	`pages`	Number of pages in the document.
`<document>`	`dpi`	Rasterization DPI applied to every page.
`<document>`	`bytes`	Size of the source document in bytes.
`<page>`	`index`	Zero-based page index within its parent document.
`<page>`	`dpi`	Rasterization DPI for the page.
`<page>`	`width` / `height`	Rasterized page dimensions in pixels at the given DPI.

Non-streaming: <document> blocks (and the <page> blocks inside them) are concatenated in order inside choices[0].message.content. Streaming: the VLM Run Gateway emits OpenAI-style SSE chunks in document order: the <document> open tag, then one chunk per <page> block, then the matching </document> close tag. The next document follows after. Split on <document>/<page> open and close tags to recover per-document and per-page markdown, or strip the tags and treat the whole string as one blob if you do not need document or page boundaries.

5. Track cost and handle errors

Non-streaming: read response.usage.cost for per-request metering during the alpha. Streaming: the last SSE event carries usage (including usage.cost) on the chunk instead of delta.content. Check for it before treating every chunk as page content:

usage = None
pages: list[str] = []

for chunk in stream:
    choice = chunk.choices[0]
    if choice.delta.content:
        pages.append(choice.delta.content)
    if chunk.usage:
        usage = chunk.usage

print(f"Cost: {usage.cost if usage else 'n/a'}")

For both modes:

Retry 429/500 with backoff; do not retry 400 capability violations. See Error Codes.
Keep the x-request-id response header if you need to contact support.

Multimodal Inputs

Content part types, document limits, and URL vs base64 tradeoffs.

Methods

Per-model method and method_params reference.

Error Codes

Status codes, error bodies, and retry guidance.

Models

Document and image OCR model catalog.

Overview

Guides

API Reference

Misc

Flexible Document OCR

1. Pick a model

2. Send the document

Request knobs

Document rasterization

3. Streaming vs non-streaming

4. Parse the response

Multiple documents in one request

Element attributes

5. Track cost and handle errors

Multimodal Inputs

Methods

Error Codes

Models

​1. Pick a model

​2. Send the document

​Request knobs

​Document rasterization

​3. Streaming vs non-streaming

​4. Parse the response

​Multiple documents in one request

​Element attributes

​5. Track cost and handle errors

​Related

Multimodal Inputs

Methods

Error Codes

Models

1. Pick a model

2. Send the document

Request knobs

Document rasterization

3. Streaming vs non-streaming

4. Parse the response

Multiple documents in one request

Element attributes

5. Track cost and handle errors

Related