GonkaGate PDF Inputs Plugin

Choose pdf-text, native, and the poppler or mistral_ocr provider for PDF inputs.

Use file-parser only when a /v1/chat/completions request must choose a PDF engine or PDF text provider explicitly. If bare PDF inputs already work for the request, you can usually omit the plugin and let GonkaGate use server-managed PDF handling. For authenticated requests with plugin settings policy enabled, omitting file-parser can still apply a saved file-parser default.

Minimum working request

request.json

{
  "model": "qwen/qwen3-235b-a22b-instruct-2507-fp8",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "file",
          "file": {
            "filename": "sample.pdf",
            "file_data": "data:application/pdf;base64,<base64-pdf>"
          }
        },
        {
          "type": "text",
          "text": "Summarize the attached PDF."
        }
      ]
    }
  ],
  "plugins": [
    {
      "id": "file-parser",
      "pdf": { "engine": "pdf-text" }
    }
  ]
}

Result: this request pins local pdf-text parsing for one PDF input. GonkaGate extracts text before the upstream model call.

For OCR on scanned or image-heavy PDFs, keep engine: "pdf-text" and set the document-processing provider:

mistral-ocr-provider.json

{
  "id": "file-parser",
  "pdf": { "engine": "pdf-text", "provider": "mistral_ocr" }
}

Choose the PDF engine and provider

Option	What GonkaGate does	Use it when	Do not choose it when
Omit `file-parser` entirely	Bare PDF handling stays enabled without the plugin. In most requests GonkaGate uses server-managed auto selection, but authenticated requests with plugin settings policy enabled can inherit a saved `file-parser` default instead.	Bare PDF support is enough and the request does not need an explicit per-request override.	The request must pin local parsing or explicitly ask for `native`, or the caller must ignore saved plugin defaults.
Omit `pdf.engine` or `pdf.provider` in `file-parser`	Uses server-managed auto selection for the missing part. Today that usually resolves to local `pdf-text` with the default provider.	The request includes `file-parser` but does not need a fixed engine or provider.	The request must pin local parsing, force OCR, or explicitly ask for `native`.
`pdf-text` with `poppler` or omitted provider	Parses the PDF locally and extracts embedded text before the upstream call. Non-stream responses can include file annotations.	You want fast text extraction from text-based PDFs at public `http/https` URLs or `data:application/pdf;base64,...`.	The PDF is scanned, textless, or image-heavy and needs OCR.
`pdf-text` with `mistral_ocr`	Runs Mistral OCR through the document-processing service, extracts text before the upstream call, and adds billable OCR processing cost only after a successful parse.	The PDF is scanned, textless, or image-heavy and embedded text extraction is not enough.	You need zero OCR processing cost, or the selected model path should receive the original PDF file for native handling.
`native`	Forwards the original PDF file and the `file-parser` plugin upstream unchanged.	The selected model path is expected to support native PDF input and you do not want gateway-side extraction.	You expect fallback to local parsing. Explicit `native` fails with `pdf_native_unavailable` when native handling is unavailable.

What changes in the request and response

pdf-text is local-only. GonkaGate extracts text before the upstream model call and strips the local-only override from the forwarded payload.
provider is valid only with pdf-text. Use poppler for embedded-text extraction or mistral_ocr for OCR.
Non-stream pdf-text responses can include reusable file annotations in choices[].message.annotations[].
Streaming responses keep the normal chat-completions SSE shape and do not add PDF annotations.
native keeps the original file part and forwards plugins: [{ "id": "file-parser", "pdf": { "engine": "native" } }] upstream unchanged.

Supported sources and practical limits

pdf-text supports public http/https URLs and data:application/pdf;base64,....
Private or local URLs are blocked by design.
The default poppler provider extracts embedded text and can fail with pdf_input_text_unavailable on scanned or textless PDFs.
The mistral_ocr provider runs OCR for scanned or image-heavy PDFs and is charged only after a successful parse.
Reusing already extracted PDF text does not add a new OCR charge.
Current default request limits are up to 5 PDF files per request and up to 1 MiB per file.
Oversized request bodies can fail with HTTP 413 payload_too_large before PDF parsing starts.

How saved plugin settings affect the request

Authenticated requests can inherit a saved file-parser default when plugin settings policy is enabled.

An enabled saved setting can supply the default PDF engine and provider even when the request omits file-parser.
For authenticated requests with plugin settings policy enabled, omitting file-parser does not guarantee server_auto. A saved file-parser default can still become the effective engine and provider.
Locked settings can reject an incompatible request override with 400 invalid_request_error and code=plugin_override_blocked.
A disabled saved file-parser setting means “no saved engine or provider preference”. It does not turn bare PDF support off.

Common failures

Error	What it means	What to do next
`400 pdf_engine_not_supported`	The request asked for an unsupported engine such as `mistral-ocr`.	Use `pdf-text` with `provider: "mistral_ocr"` for OCR, or use `native`.
`400 pdf_provider_not_supported`	The request asked for an unsupported provider, or combined `provider` with `native`.	Use `poppler` or `mistral_ocr` only with `engine: "pdf-text"`.
`400 pdf_native_unavailable`	The request explicitly asked for `native`, but the selected model/runtime cannot use native PDF handling right now.	Omit the engine for auto handling or switch to `pdf-text`.
`400 plugin_override_blocked`	Locked saved plugin settings conflict with the request override.	Remove the override or align the request with the saved account policy.
`400 pdf_input_not_supported` or `400 pdf_input_invalid_data_url`	The PDF source is not valid for `pdf-text`.	Use a public `http/https` URL or a valid `data:application/pdf;base64,...` payload.
`400 pdf_input_text_unavailable`	The default text provider could not extract usable embedded text.	Switch to `provider: "mistral_ocr"` for OCR, or send a text-based PDF.
`413 payload_too_large` or `400 pdf_input_too_large`	The body or file exceeds the active size budget.	Reduce file size/count or prefer URL mode instead of embedding large data URLs.

PDF Inputs