# 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.

By Paras Madan | 2026-11-12


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](https://openrouter.ai/blog/announcements/extractions-api/) 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](https://openrouter.ai/docs/api/api-reference/alphaextractions/submit-an-extractions-request) 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:

```bash
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](https://openrouter.ai/docs/guides/community/extractions) 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](https://openrouter.ai/cloudflare/clairic) lists $0.10 per million input tokens and free output. [ScaleDown Extract](https://openrouter.ai/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](https://cal.com/paras-madan/30min).