Skip to main content
Invoice OCR uses environment variables for configuration. All variables should be set in .env.local (not committed to version control).

​
Quick Setup

cp .env.example .env.local
Then edit .env.local with your values.
Never commit .env.local to version control. This file is included in .gitignore by default.

​
Required Variables

​
OPENROUTER_API_KEY
string
required
Your OpenRouter API key for accessing vision models.How to get it:
  1. Sign up at openrouter.ai
  2. Navigate to openrouter.ai/keys
  3. Create a new API key
  4. Copy the key to your .env.local file
Example:
OPENROUTER_API_KEY=sk-or-v1-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
The application will fail with a 500 error if this variable is not set. All API routes check for this key before processing requests.

​
Model Configuration

​
OPENROUTER_MODEL
string
default:"google/gemini-2.0-flash"
Default vision model for OCR operations.Used by:
  • /api/ocr (raw text extraction)
  • /api/ocr-structured (legacy structured extraction)
  • /api/ocr-structured-v4 (normalized GST extraction)
Fallback behavior:
  • If not set: defaults to google/gemini-2.0-flash
  • Can be overridden per-request via the model field in API request body
Example values:
# Fast and cost-effective (default)
OPENROUTER_MODEL=google/gemini-2.0-flash

# Higher accuracy
OPENROUTER_MODEL=openai/gpt-4o
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

# Budget option
OPENROUTER_MODEL=openai/gpt-4o-mini
See Model Selection for guidance on choosing the right model for your use case.

​
PDF Processing

​
OPENROUTER_PDF_ENGINE
string
default:"pdf-text"
PDF parsing engine used by OpenRouter’s file-parser plugin.Available engines:
  • pdf-text (default) - Fast text extraction, works with most PDFs
  • mistral-ocr - OCR-based extraction for scanned PDFs or images within PDFs
  • native - Provider’s native PDF handling
Used by:
  • /api/ocr when processing PDFs
  • /api/ocr-structured-v4 when processing PDFs
Example:
OPENROUTER_PDF_ENGINE=pdf-text
Per-request override: You can override this setting by passing a plugins array in the request body:
{
  "pdfBase64": "...",
  "plugins": [
    {
      "id": "file-parser",
      "pdf": { "engine": "mistral-ocr" }
    }
  ]
}

​
OpenRouter Metadata

These variables are sent as headers to OpenRouter for analytics and billing purposes.
​
OPENROUTER_SITE_URL
string
default:"http://localhost:3000"
Your application’s URL, sent in the HTTP-Referer header.Example:
OPENROUTER_SITE_URL=https://invoice-ocr.yourdomain.com
OpenRouter uses this for analytics and to help identify your application in their dashboard.
​
OPENROUTER_APP_NAME
string
default:"Invoice OCR"
Your application’s name, sent in the X-Title header.Example:
OPENROUTER_APP_NAME=My Invoice OCR App

​
Complete Example

Here’s a complete .env.local file with all variables configured:
.env.local
# Required: Your OpenRouter API key
OPENROUTER_API_KEY=sk-or-v1-1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

# Optional: Model selection (defaults to google/gemini-2.0-flash)
OPENROUTER_MODEL=google/gemini-2.0-flash

# Optional: PDF engine (defaults to pdf-text)
OPENROUTER_PDF_ENGINE=pdf-text

# Optional: Metadata for OpenRouter
OPENROUTER_SITE_URL=http://localhost:3000
OPENROUTER_APP_NAME=Invoice OCR

​
Environment Variable Priority

For each API route, the priority order is:
  1. Request body parameter (e.g., model field in POST body)
  2. Environment variable (from .env.local)
  3. Default value (hardcoded in the route)

​
Example: Model Selection

const model = body.model || process.env.OPENROUTER_MODEL || "google/gemini-2.0-flash";
This allows you to:
  • Set a default model in .env.local
  • Override it per-request when needed
  • Fall back to a sensible default if neither is provided

​
Troubleshooting

This means OPENROUTER_API_KEY is not set in your .env.local file.Solution:
  1. Create .env.local if it doesn’t exist
  2. Add OPENROUTER_API_KEY=your-key-here
  3. Restart the development server
Next.js loads environment variables at startup.Solution:
  • Stop the dev server (Ctrl+C)
  • Restart with npm run dev
The application filters API keys from error messages, but be cautious.Best practices:
  • Never log process.env.OPENROUTER_API_KEY
  • Use server-side only (never expose to client)
  • Rotate keys regularly

​
Next Steps

OpenRouter Setup

Step-by-step guide to getting your OpenRouter API key

Model Selection

Choose the right model for your use case

Build docs developers (and LLMs) love

Get started for freeTalk to us