# OpenRouter's Extractions API alpha: can it carry documents?

URL: https://infro.io/blog/openrouter-s-extractions-api-alpha-can-it-carry-documents
Author: INFRO Editorial (https://infro.io/blog/editorial)
Publisher: INFRO
Published: 2026-11-13
Last modified: 2026-11-13
Last reviewed: 2026-11-13 (next review due 2026-12-13)
Topic: Agents and multimodal systems
Format: Brief

> Treat it as a candidate for a slice of traffic, not a replacement for your extraction path. OpenRouter says the route is alpha and its shape can change[^or-docs], and PDFs, numbers and dates are not covered by one model today[^or-announce].

Key takeaways:
- The route is alpha and OpenRouter says its shape can change, so pin the contract with tests rather than trust it.
- The three launch models split the work: Clairic reads text and images, ScaleDown Extract reads a PDF but returns only text and list fields.
- Cost follows schema size as well as document size, because schema tokens are billed as input.
- Fields return values with confidence and null probability, which is a different guarantee from strict JSON Schema output.
- Before moving traffic, replay a labelled set through both paths and compare field accuracy, null handling, cost and failure behaviour.

## What the route is, and what alpha means

`POST /api/alpha/extractions` takes a `state` (text, or the key of an image or PDF in `assets`) and a `fields` map. You get one typed answer per field.[1] The docs state it plainly: the route is alpha and its shape can change.[2] The path itself carries `alpha`, so treat any field name, error code or limit as provisional.

Two details matter for production. Unknown keys at the top level or inside a field are rejected with a 400 rather than ignored. A request a model cannot serve, such as a date field on a text-only model, fails with a 400 before anything reaches the provider.[2] That is good for catching mistakes. It also means a schema that works on one model can fail on another.

## Which model reads what

The launch announcement names three models; the docs page already lists more, which shows how fast the surface moves.[1][2]

| Model | Reads | Field types |
| --- | --- | --- |
| cloudflare/clairic | Text and up to 4 images (PNG/JPEG; docs add WebP) | Every type |
| scaledown/extract | Text, or one PDF or image | text, list of text |
| inception/mercury-decide | Text only | text, list of text |

Table: Launch models as described by OpenRouter on 2026-11-10 and in its docs.

The consequence for invoices: a scanned PDF goes to ScaleDown Extract, which has no number or date types, so the total comes back as a string such as "$4,200.00" and you parse it.[1] The model that returns numbers, dates and null probabilities does not read PDFs. The documented field types also have no object type; a list holds text, number or date items.[2] Line items as structured rows need a different design.

## Pricing: schema tokens count

The announcement lists input prices per million tokens (Clairic $0.10, Extract $0.04, Mercury Decide $0.02), output free, as catalog values on November 6, with the model pages holding current ones.[1] Those are the provider's rates on OpenRouter, so treat them as a snapshot.

The usage block shows what you are billed on. In the announcement's text example, 1,138 input tokens split into 118 state tokens and 666 schema tokens.[1] The schema, not the document, was most of the bill. Cost per document therefore rises with field count and `instructions` length. Measure it on your real schema.

> **Example: Illustrative arithmetic**
> Suppose a 30-field schema costs 2,000 schema tokens and a document 500 tokens. At a hypothetical $0.10 per million input tokens, a call is about $0.00025, and 80% of it is schema. Cutting unused fields would move cost more than shortening documents. These figures are made up to show the shape, not measured.

## Schema guarantees are a different kind

Strict structured outputs ask a chat model to emit JSON matching your schema, and OpenRouter notes that enforcement varies by provider: some guarantee conformance, others treat it as a strong hint.[3] Extractions answers differently. Each value comes with `confidence`, and single values carry `p_null`, the probability the document holds nothing for the field. A value becomes null above 0.5 unless you set `null_threshold`, and `guess` shows what the model would have reached for.[1]

So the type is reliable, but correctness is probabilistic and you route on confidence. The announcement's own receipt example returned a wrong merchant name ("NORTH HAROR C") with a spell confidence of 0.73.[1] A pipeline without a confidence floor would have stored it. Extract returns a confidence per value but no `p_null` or span, so null handling differs per model.

Separately, OpenRouter's own OCR measurements found vision models writing plausible values that were not on the page, such as invented card digits.[4] Confidence thresholds help, but only a labelled set tells you whether they are calibrated for your documents.

## Fallbacks: assume you build them

For chat requests OpenRouter says it falls back to other providers on a 5xx or rate limit.[5] The documented Extractions envelope lists `model`, `state`, `assets`, `provider`, `user`, `session_id` and `trace`, with no fallback list.[2] Fallback across extraction models is also a schema problem: Mercury Decide cannot answer a date field, so a fallback needs its own reduced schema and its own parsing. Confirm the alpha behaviour with OpenRouter before relying on it.

INFRO's docs list endpoints for chat, images, video, speech, transcription, embeddings, decisions and rerank, but no extractions route.[6] If your current path is chat completions with a JSON schema, that path can keep its routing, failover and per-request cost records while you test the alpha beside it. The alpha endpoint is not routable through INFRO today.

## A test before any traffic moves

1. Build a labelled set of 200 or more real documents, stratified by type: clean PDFs, scans, photos, web pages, and some with missing fields.
2. Replay them through your current path and the alpha route with the same fields. Keep the alpha schema minimal.
3. Score per field, not per document: exact match, null correctness, and parse success for numbers and dates.
4. Sweep a confidence floor and record, at each floor, the share auto-accepted and the error rate in that share.
5. Record cost per document from the `usage` block, and p95 latency.
6. Inject failures: an unsupported field, a fifth image, an oversized PDF. Check that your code handles each 400 and that `truncated` is false.
7. Re-run weekly while the route is alpha and diff the results.

```python
def score(gold, got, floor=0.9):
    out = {"auto": 0, "wrong_auto": 0, "review": 0}
    for name, truth in gold.items():
        a = got["answers"][name]
        c = a.get("confidence", 1.0)
        if a["value"] is None and truth is not None or c < floor:
            out["review"] += 1
        else:
            out["auto"] += 1
            out["wrong_auto"] += a["value"] != truth
    return out
```

Move traffic only for the document types where the wrong-auto rate at your chosen floor matches your current path, and keep the old path warm for the rest.

## Questions

### Can I send a PDF with numbers and dates through one model?

Not at launch, going by OpenRouter's own pages. The PDF-capable model, ScaleDown Extract, answers text and list-of-text fields only, so totals and dates come back as strings you parse yourself[1].

### Does the alpha route fail over to another model?

The documented request envelope lists model, state, assets, provider, user, session_id and trace[2]. It names no fallback list, so plan to retry or fail over in your own code and confirm with OpenRouter.

## Sources

1. Introducing the Extractions API — OpenRouter. https://openrouter.ai/blog/announcements/extractions-api/ (accessed 2026-11-13)
2. Extractions API: Typed Fields from Text, Images, and PDFs — OpenRouter. https://openrouter.ai/docs/guides/community/extractions (accessed 2026-11-13)
3. Structured Outputs — OpenRouter. https://openrouter.ai/docs/guides/features/structured-outputs (accessed 2026-11-13)
4. Best OCR Model for Scanned Documents, Measured — OpenRouter. https://openrouter.ai/blog/insights/best-ocr-model/ (accessed 2026-11-13)
5. OpenRouter API Reference overview — OpenRouter. https://openrouter.ai/docs/api_reference/overview (accessed 2026-11-13)
6. INFRO documentation — INFRO. https://infro.io/docs (accessed 2026-11-13)
