Native OCR Endpoint

For new integrations, we recommend using the Chat Completions endpoint which is compatible with OpenAI SDKs.

The /v1/ocr endpoint is DocsRouter's native OCR format. It provides a simpler request structure for basic OCR use cases where you just need to extract text from a single image or document.

Endpoint

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

Authentication

All requests require authentication via the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can obtain an API key from the DocsRouter Dashboard.

Request Headers

Header	Required	Description
`Authorization`	Yes	Bearer token: `Bearer YOUR_API_KEY`
`Content-Type`	Yes	Must be `application/json`

Request Body

The request body should be a JSON object with the following properties:

Field	Type	Required	Description
`url`	string	No*	Publicly accessible URL of the image/document.
`base64`	string	No*	Base64-encoded image data (without data URI prefix).
`model`	string	No	The ID of the model to use. Default: `google/gemini-2.0-flash-001`.
`options`	object	No	Additional processing options.

* Either url or base64 is required.

Options Object

Field	Type	Default	Description
`extract_tables`	boolean	`false`	If true, attempts to parse tables into structured JSON.
`language`	string	`auto`	Hint for the document language (e.g., "en", "es").
`output_format`	enum	`text`	Preferred output format: `text`, `json`, `markdown`.

Example Request

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.jpg",
    "model": "openai/gpt-4o",
    "options": {
      "extract_tables": true
    }
  }'

Response Body

{
  "id": "req_123...",
  "object": "ocr.result",
  "created": 1716312345,
  "model": "openai/gpt-4o",
  "result": {
    "text": "INVOICE #001...",
    "blocks": [
      { "type": "text", "content": "INVOICE #001" },
      ...
    ],
    "tables": [
      {
        "headers": ["Item", "Price"],
        "rows": [["Widget", "$10.00"]]
      }
    ],
    "confidence": 95,
    "language": "en"
  },
  "usage": {
    "pages_processed": 1,
    "tokens_used": 450,
    "provider_cost_cents": 2,
    "platform_fee_cents": 1,
    "total_cost_cents": 3,
    "processing_time_ms": 1800
  }
}

Response Fields

Field	Type	Description
`id`	string	Unique request identifier
`object`	string	Always `ocr.result`
`created`	number	Unix timestamp of when the request was processed
`model`	string	The model that was used
`result`	object	The OCR results
`result.text`	string	Full extracted text
`result.blocks`	array	Text blocks with position information
`result.tables`	array	Extracted tables (if `extract_tables` was true)
`result.confidence`	number	Overall confidence score (0-100)
`result.language`	string	Detected language code
`usage`	object	Usage and cost information

Additional Examples

With Base64 Image

# Encode your image to base64
IMG_BASE64=$(base64 -i document.png | 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": "'"$IMG_BASE64"'",
    "model": "google/gemini-2.0-flash-001"
  }'

With Language Hint

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/german-invoice.jpg",
    "options": {
      "language": "de",
      "output_format": "markdown"
    }
  }'

JSON Output Format

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/receipt.jpg",
    "options": {
      "output_format": "json",
      "extract_tables": true
    }
  }'

Error Handling

Status Code	Description
400	Bad Request - Invalid parameters or missing image
401	Unauthorized - Invalid or missing API key
402	Payment Required - Insufficient credits
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Comparison with Chat Completions

Feature	Native OCR (`/v1/ocr`)	Chat Completions (`/v1/chat/completions`)
SDK Compatibility	DocsRouter only	OpenAI, OpenRouter, LangChain, etc.
Request Format	Simple flat structure	OpenAI messages format
Multi-image Support	Single image only	Multiple images per request
Custom Prompts	Limited	Full prompt customization
PDF Support	Images only	Images and PDFs
Streaming	No	Yes

For most use cases, we recommend the Chat Completions endpoint for its flexibility and SDK compatibility.

Native OCR Endpoint

On this page