Native OCR Endpoint

POST /v1/ocr accepts one image or document as a public URL or unprefixed base64 data. You can choose a model returned by GET /v1/models or use a transparent routing policy.

Endpoint

POST https://api.docsrouter.com/v1/ocr

All requests require a bearer API key:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request body

Provide exactly one of url or base64.

Options

These options guide the selected model. They do not guarantee that every document will produce a particular structure.

Choose a model

Explicit model

curl -X POST https://api.docsrouter.com/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/invoice.png",
    "model": "openai/gpt-4o",
    "options": {"extract_tables": true, "output_format": "markdown"}
  }'

Routing policy

curl -X POST https://api.docsrouter.com/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/invoice.png",
    "strategy": "balanced"
  }'

Policies use fixed mappings documented on Models. They do not run benchmarks, inspect confidence, or retry with a second model.

Base64 input

DOCUMENT_BASE64=$(base64 -i document.pdf | tr -d '\n')

curl -X POST https://api.docsrouter.com/v1/ocr \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64": "'"$DOCUMENT_BASE64"'",
    "mime_type": "application/pdf",
    "strategy": "quality"
  }'

Multi-page documents

Supported PDFs and office documents can contain multiple pages. DocsRouter processes the pages and returns:

• combined text in result.text
• one entry per page in result.pages
• flattened table data in result.tables
• the processed page count in usage.pages_processed

Some formats require the document-conversion service. If conversion is not configured, the endpoint returns conversion_not_available instead of silently changing behavior.

Response

{
  "id": "req_123",
  "object": "ocr.result",
  "created": 1785400000,
  "model": "google/gemini-2.5-flash",
  "result": {
    "text": "Page one text\n\nPage two text",
    "pages": [
      {"page_number": 1, "text": "Page one text"},
      {"page_number": 2, "text": "Page two text"}
    ],
    "tables": []
  },
  "usage": {
    "pages_processed": 2,
    "prompt_tokens": 2400,
    "completion_tokens": 300,
    "tokens_used": 2700,
    "provider_cost_cents": 1,
    "platform_fee_cents": 1,
    "total_cost_cents": 2,
    "processing_time_ms": 1800
  }
}

result.confidence and page-level confidence values can appear when the selected model returns a valid score. They are optional model output, not a measured DocsRouter benchmark or a trigger for automatic fallback.

Pricing

Vision-model requests use the provider cost plus a 5% DocsRouter platform fee. Small requests are affected by minimum charges and cent rounding. The response is the source of truth for the charged amount.

Errors

DocsRouter does not automatically retry a failed extraction with a different model. Your application can decide whether and when to retry after examining the response.