Skip to main content
The Invoice OCR API provides endpoints to extract text and structured data from invoice images and PDFs using vision-language models via OpenRouter.

​
Base URL

All API endpoints are relative to your deployment base URL: 
https://your-domain.com/api
For local development: 
http://localhost:3000/api

​
Authentication

The API uses OpenRouter for model inference. Configure your OpenRouter API key in the environment:
.env.local
OPENROUTER_API_KEY=your_key_here
The API routes handle authentication with OpenRouter internally - clients do not need to provide API keys in requests.

​
Environment Configuration

​
OPENROUTER_API_KEY
string
required
Your OpenRouter API key (required)
​
OPENROUTER_MODEL
string
default:"openai/gpt-4o-mini"
Default model for inference. Can be overridden per request.
​
OPENROUTER_SITE_URL
string
default:"http://localhost:3000"
Your site URL for OpenRouter HTTP-Referer header
​
OPENROUTER_APP_NAME
string
default:"Invoice OCR"
Application name for OpenRouter X-Title header
​
OPENROUTER_PDF_ENGINE
string
default:"pdf-text"
PDF parsing engine: pdf-text, mistral-ocr, or native

​
Endpoints

​
OCR Extraction Endpoints

POST /api/ocr

Extract raw text from images or PDFs without structuring

POST /api/ocr-structured

Extract structured JSON using MyBillBook schema with reconciliation

POST /api/ocr-structured-v4

Advanced India GST schema with comprehensive reconciliation

GET /api/models

List available vision-capable OpenRouter models

​
Input Formats

All endpoints support multiple input formats:
  • Base64 Image: imageBase64 parameter with optional mimeType
  • Data URL: imageBase64 with data:image/png;base64,... format
  • PDF URL: pdfUrl parameter with publicly accessible URL
  • Base64 PDF: pdfBase64 parameter

​
Response Format

All endpoints return JSON responses: Success (200) 
{
  // Endpoint-specific response structure
}
Error (400/500) 
{
  "error": "Error message describing the issue"
}

​
Model Selection

You can override the default model per request: 
{
  "imageBase64": "...",
  "model": "anthropic/claude-3.5-sonnet"
}
Supported models depend on your OpenRouter plan. Popular choices:
  • openai/gpt-4o-mini - Fast and cost-effective
  • openai/gpt-4o - Higher accuracy
  • google/gemini-2.0-flash - Excellent for PDFs
  • anthropic/claude-3.5-sonnet - High quality extraction

​
Error Handling

Common error scenarios: 
{
  "error": "Provide 'imageBase64' or 'pdfUrl' or 'pdfBase64'"
}
Include at least one input format in your request.
{
  "error": "Server missing OPENROUTER_API_KEY"
}
Configure OPENROUTER_API_KEY in your environment.
{
  "error": "OpenRouter error: 401 Invalid API key"
}
Check your OpenRouter API key and account status.
{
  "error": "No content returned from model"
}
The model failed to generate output. Try a different model or input.

​
Rate Limits

Rate limits are determined by your OpenRouter plan. The API does not impose additional limits.

​
Best Practices

1

Start with Raw OCR

Test /api/ocr first to verify the model can read your invoice format
2

Choose the Right Endpoint

Use /api/ocr-structured-v4 for India GST invoices, /api/ocr-structured for simpler formats
3

Handle Reconciliation

Check reconciliation.status in structured responses to detect calculation mismatches
4

Optimize Model Selection

Balance cost and accuracy based on your invoice complexity

​
Next Steps

Raw Text Extraction

Learn about the /api/ocr endpoint

Structured Extraction

Explore the MyBillBook schema

V4 Schema

Advanced India GST extraction

Request Formats

Learn about all supported input formats

Build docs developers (and LLMs) love

Get started for freeTalk to us