# extract.embeddings

> Split a PDF into chunks and embed each one through OpenRouter (EU region and mistral-embed by default), for retrieval.

> Coming soon. The hosted API is not live yet, and this page describes the planned service as of 16 November 2026. [Get notified](https://pdfluent.com/contact/?topic=hosted) when it opens.

Source: https://pdfluent.com/docs/api/reference/extract-embeddings/

Split a PDF into chunks and embed each one through OpenRouter (EU region and mistral-embed by default), for retrieval.

`POST /v1/extract/embeddings`

| | |
|---|---|
| Input | one file, sent as `multipart/form-data`; the optional `options` part is a JSON object |
| Output | JSON |
| Credits | credits per page by quality: `fast` 1, `auto` 3 |
| Limits | [size, page and time limits: no claim ID yet] |
| Reads or changes the document | reads only |
| Error statuses | 400, 413, 422, 500, 501, 504 (see [Errors](https://pdfluent.com/docs/api/errors/)) |

## Options

| Option | Type | Required | Default | Description |
|---|---|---|---|---|
| `chunking_strategy` | string | no |  | How chunks are formed. Default `structure`. `structure`: The engine's structure-aware chunker: headings, lists and tables drive the splits. The default, and what this operation did before the strategies below existed. `basic`: Pack elements in reading order up to the budget. Tables stand alone. `by_title`: A new chunk starts at every title; small sections can be combined. `by_page`: A new chunk starts at every page. |
| `combine_text_under_n_chars` | integer | no | `0` | Merge sections shorter than this with the next one. |
| `max_characters` | integer | no | `1000` | Most Unicode characters in a chunk. Default 1000. |
| `model` | string | no |  | The model. In `eu`: `mistral-embed` (default), `gemini-embedding-2` or `codestral-embed`. In `global`: an id of OpenRouter's embeddings catalogue, for example `baai/bge-m3`; an unknown id is refused. With your own provider key (BYOK) the model is required and is passed on as given. The answer always names the model id used. |
| `multipage_sections` | boolean | no | `true` | `by_title`: let a section run across a page boundary. Default true. |
| `new_after_n_chars` | integer | no |  | Close a chunk once it has this many characters. |
| `overlap` | integer | no | `100` | Characters shared between neighbouring pieces of one split element. Default 100. |
| `pages` | array of integer | no |  | One-based pages. Default: all pages. |
| `password` | string | no |  | Password of an encrypted document. |
| `quality` | string | no |  | Extraction quality tier. Default `fast`. `fast`: Geometric extraction, no model, no OCR. The default. `auto`: `fast` plus OCR of scanned pages. Answers `quality_unavailable` (501) on a deployment without an OCR engine; it never reads `fast` in its place. |
| `region` | string | no |  | Where the embedding runs. Default `eu`. `eu`: OpenRouter's EU endpoint. Allows `mistral-embed` (default), `gemini-embedding-2` and `codestral-embed` only. The default. `global`: An explicit opt-in to OpenRouter's whole embeddings catalogue, by OpenRouter model id. The data leaves the EU; the answer says so in `data_left_eu` and in a header. |

## Example

### curl

```sh
curl -sS -f -X POST "$PDFLUENT_API_URL/v1/extract/embeddings" \
  -H "x-api-key: $PDFLUENT_API_KEY" \
  -F file=@structured.pdf \
  -F 'options={"max_characters":500}' \
  -o result.json
```

### Python

```python
import json
import os

import requests

options = {"max_characters": 500}

parts = [
    ("file", ("structured.pdf", open("structured.pdf", "rb"))),
    ("options", (None, json.dumps(options))),
]

response = requests.post(
    os.environ["PDFLUENT_API_URL"] + "/v1/extract/embeddings",
    headers={"x-api-key": os.environ["PDFLUENT_API_KEY"]},
    files=parts,
)
response.raise_for_status()

with open("result.json", "wb") as out:
    out.write(response.content)
```

### Node.js

```js
import { openAsBlob } from 'node:fs';
import { writeFile } from 'node:fs/promises';

const form = new FormData();
form.append('file', await openAsBlob("structured.pdf"), "structured.pdf");
form.append('options', JSON.stringify({"max_characters":500}));

const response = await fetch(process.env.PDFLUENT_API_URL + "/v1/extract/embeddings", {
  method: 'POST',
  headers: { 'x-api-key': process.env.PDFLUENT_API_KEY },
  body: form,
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);

await writeFile("result.json", Buffer.from(await response.arrayBuffer()));
```

The key goes in the `x-api-key` header; see [Authentication](https://pdfluent.com/docs/api/authentication/). Every response carries `x-pdfluent-pages` and `x-pdfluent-credits`.
