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