Invoice OCR supports multiple input formats for both images and PDFs. This page documents all supported request body structures across the API endpoints.
Image Requests Base64 Encoded Image The most common format for uploading images directly from client applications.
Image data as a base64-encoded string or data URL
MIME type of the image (e.g., “image/png”, “image/jpeg”). Defaults to “image/png” if omitted.
curl -X POST http://localhost:3000/api/ocr-structured-v4 \ -H "Content-Type: application/json" \ -d '{ "imageBase64": "iVBORw0KGgoAAAANSUhEUgAA...", "mimeType": "image/png" }'
const response = await fetch ( '/api/ocr-structured-v4' , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ imageBase64: 'iVBORw0KGgoAAAANSUhEUgAA...' , mimeType: 'image/png' }) });
import requests import base64 with open ( 'invoice.png' , 'rb' ) as f: image_data = base64.b64encode(f.read()).decode( 'utf-8' ) response = requests.post( 'http://localhost:3000/api/ocr-structured-v4' , json = { 'imageBase64' : image_data, 'mimeType' : 'image/png' } )
You can also pass a complete data URL (useful when reading from file inputs in the browser).
{ "imageBase64" : "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." }
When using a data URL, the mimeType parameter is optional as it’s embedded in the data URL.
PDF Requests Public PDF URL The simplest format for PDFs - provide a publicly accessible URL.
Publicly accessible URL to the PDF document
curl -X POST http://localhost:3000/api/ocr-structured-v4 \ -H "Content-Type: application/json" \ -d '{ "pdfUrl": "https://example.com/invoices/invoice-001.pdf" }'
The PDF must be accessible without authentication. OpenRouter will fetch the document from this URL.
Base64 Encoded PDF For PDFs that aren’t publicly accessible or when uploading directly.
PDF data as a base64-encoded string or data URL
curl -X POST http://localhost:3000/api/ocr-structured-v4 \ -H "Content-Type: application/json" \ -d '{ "pdfBase64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8..." }'
// Reading from file input const file = document . getElementById ( 'pdfInput' ). files [ 0 ]; const reader = new FileReader (); reader . onload = async ( e ) => { const base64 = e . target . result . split ( ',' )[ 1 ]; const response = await fetch ( '/api/ocr-structured-v4' , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ pdfBase64: base64 }) }); }; reader . readAsDataURL ( file );
import base64 import requests with open ( 'invoice.pdf' , 'rb' ) as f: pdf_data = base64.b64encode(f.read()).decode( 'utf-8' ) response = requests.post( 'http://localhost:3000/api/ocr-structured-v4' , json = { 'pdfBase64' : pdf_data} )
PDF Data URL Similar to images, you can use a data URL format:
{ "pdfBase64" : "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MKMyAwIG9iago8..." }
Advanced Options Model Override Override the default OpenRouter model for a specific request.
OpenRouter model ID (e.g., “openai/gpt-4o”, “google/gemini-2.0-flash”)
{ "imageBase64" : "iVBORw0KGgoAAAANSUhEUgAA..." , "model" : "openai/gpt-4o" }
Use this for A/B testing different models or for processing complex invoices with more powerful models.
PDF Plugin Configuration Configure the PDF parsing engine and options.
Array of OpenRouter plugin configurations. Typically used to override the PDF parser.
{ "pdfUrl" : "https://example.com/invoice.pdf" , "plugins" : [ { "id" : "file-parser" , "config" : { "engine" : "mistral-ocr" } } ] }
Available PDF Engines: Engine Description Use Case pdf-textFast text extraction (default) Standard PDFs with selectable text mistral-ocrOCR-based extraction Scanned PDFs, image-based documents nativeNative OpenRouter parsing When you want model-native PDF handling
If omitted, the system uses the OPENROUTER_PDF_ENGINE environment variable (defaults to pdf-text).
Annotations (Cost Optimization) Reuse previously parsed PDF metadata to avoid redundant processing costs.
OpenRouter annotations from a previous response. When provided, skips re-parsing the PDF.
{ "pdfUrl" : "https://example.com/invoice.pdf" , "annotations" : { "file-parser" : { "output" : { "text" : "..." , "pages" : [ ... ] } } } }
Workflow:
First request: Process PDF normally, save annotations from response
Subsequent requests: Include saved annotations to reuse parsed content
Cost savings: Avoid file-parser plugin charges on repeated requests
Example: Reusing Annotations
// First request - parse PDF const firstResponse = await fetch ( '/api/ocr-structured-v4' , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ pdfUrl: 'https://example.com/invoice.pdf' }) }); const firstData = await firstResponse . json (); const annotations = firstData . annotations ; // Save these // Second request - reuse parsed content with different model const secondResponse = await fetch ( '/api/ocr-structured-v4' , { method: 'POST' , headers: { 'Content-Type' : 'application/json' }, body: JSON . stringify ({ pdfUrl: 'https://example.com/invoice.pdf' , annotations: annotations , // Reuse! model: 'openai/gpt-4o' // Try a different model }) });
Complete Request Examples Minimal Image Request { "imageBase64" : "iVBORw0KGgoAAAANSUhEUgAA..." }
Full-Featured PDF Request { "pdfUrl" : "https://example.com/invoice.pdf" , "model" : "openai/gpt-4o" , "plugins" : [ { "id" : "file-parser" , "config" : { "engine" : "mistral-ocr" } } ] }
Cost-Optimized Repeated Request { "pdfBase64" : "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8..." , "annotations" : { "file-parser" : { "output" : { "text" : "..." , "pages" : [ ... ] } } }, "model" : "google/gemini-2.0-flash" }
Request Size Limits Maximum request sizes:
Images: 10 MB (base64 encoded)
PDFs: 10 MB (base64 encoded or via URL)
Total request body: 10 MB
Larger files may result in timeout or error responses. Supported File Types Images
PNG (.png)
JPEG (.jpg, .jpeg)
WebP (.webp)
BMP (.bmp)
GIF (.gif)
PDFs
PDF 1.4 through 2.0
Single or multi-page documents
Text-based or scanned (with OCR engine)
Error Handling Common request validation errors:
Error Cause Solution Missing image or PDF inputNo image/PDF parameter provided Include imageBase64, pdfUrl, or pdfBase64 Invalid base64 formatMalformed base64 string Verify base64 encoding File too largeFile exceeds 10 MB Compress or reduce file size Invalid model IDUnknown model specified Use a valid OpenRouter model ID
OCR Endpoints Explore all available API endpoints
Model Selection Choose the right model for your use case
Processing PDFs Guide to working with PDF documents
PDF Support Learn about PDF processing features
