OpenRouter Extractions API: PDF Support, Model Choice and Common Errors

The new alpha endpoint returns typed fields, but changing the model can change which documents and field types your workflow accepts.

OpenRouter’s Extractions API turns documents into named fields rather than a chat response. The alpha launched on November 10, but its models are not interchangeable: ScaleDown Extract reads PDFs, while Cloudflare Clairic handles images and richer types such as numbers and dates. Choose the input format before choosing the price.

Which extraction model should you use?

The launch announcement introduced three models. For a contract PDF, start with ScaleDown Extract. For a receipt photo that needs a numeric total, use Clairic. Mercury Decide is another option for extracting names or phrases from plain text.

Job	Model	Important boundary
Read a PDF	`scaledown/extract`	Text fields and lists of text, not typed numbers or dates
Read receipt images	`cloudflare/clairic`	Rich field types, but no PDF input
Pull names from text	`inception/mercury-decide`	Text and text-list fields on this endpoint

Current documentation also lists Sage 2 and two Perplexity Decider models. The practical lesson is to discover support for this particular endpoint, rather than assume a model’s general multimodal label applies here. This is an alpha interface, so pin a tested request shape in your application and review changes before upgrading it.

A minimal request you can adapt

The API reference uses POST /api/alpha/extractions, with the document in state and the desired values in fields. Here is an illustrative text request, not a result from a test I ran:

curl https://openrouter.ai/api/alpha/extractions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cloudflare/clairic",
    "state": "Invoice LAB-104. Total due USD 275.00.",
    "fields": {
      "invoice_number": {"type": "text"},
      "total": {"type": "number", "decimals": 2, "unit": "USD"}
    }
  }'

For this fictional invoice, your acceptance test should require LAB-104 and a numeric value of 275. Separately test a missing total, conflicting totals and a credit note. A valid JSON response tells you that parsing worked; it does not establish that the accounting interpretation is correct.

Why a PDF request can return 400

The current extraction guide is more useful than copying a generic chat request. ScaleDown accepts one PDF, PNG or JPEG, but not WebP, and reads either the file or the text rather than both. Use a file-only request for a PDF. Clairic supports up to four PNG, JPEG or WebP images, with 4 MiB per image, 8 MiB combined and a 16 MiB request-body limit.

A date field on Mercury Decide, a PDF sent to Clairic or questions sent instead of fields produces a validation error. Unknown keys are rejected too. Fix the request described by the error instead of repeatedly switching providers.

Also check truncated. A successful response with that flag set means only a prefix was read. It should not silently become a complete record in your database.

Pricing is only one part of the choice

On November 12, Clairic’s catalog page lists $0.10 per million input tokens and free output. ScaleDown Extract lists $0.04 per million input tokens and free output, with a 20% promotional discount displayed. Neither page currently lists EU in-region routing as available.

Those rates do not make ScaleDown a drop-in cheaper Clairic. If a PDF total arrives as text, your application still needs currency normalization and validation. Compare the cost of an accepted, checked record, including retries and review, rather than the price of a million tokens alone.

Keep missing values missing

Clairic can return p_null, while ScaleDown does not expose that probability. Do not force both into a shared confidence rule that treats absent metadata as zero. Nor should a fallback replace an explicit missing value with the model’s best guess merely to fill every database column.

The useful change is a cleaner boundary between extraction and application logic. Keep the original document, preserve uncertainty and make the review queue part of the first version. A cheaper extraction call is valuable only if it does not turn ambiguity into an expensive downstream mistake.

I’m Paras. I work at the intersection of AI, engineering and distribution.

I help developer-tool teams turn technical launches and workflow details into clear writing that developers can use and share.

Book a 30-minute call.