Vision Router Node.js Client

Official Node.js client library for Vision Router - The unified OCR and Vision AI API.

Features

• 🔄 Multiple OCR Providers: Support for Google Vision, AWS Textract, Mistral OCR, and Custom APIs
• 🎯 Intelligent Routing: Automatic provider selection based on image type
• 🛡️ Type Safety: Full TypeScript support with comprehensive type definitions
• ⚡ Easy Integration: Simple, intuitive API similar to popular libraries
• 🔐 Secure: Built-in API key authentication
• 📊 Credit Tracking: Real-time credit usage and remaining balance
• 🚀 Promise-based: Modern async/await support

Installation

npm install visionrouter

Quick Start

import visr from 'visionrouter';

const client = new visr({
  apiKey: 'your-api-key-here'
});

// Scan an image with OCR
const result = await client.scan({
  image: 'https://example.com/image.jpg',
  provider: 'auto'
});

console.log(result.data.text);

Authentication

Get your API key by signing up at visionrouter.up.railway.app.

const client = new visr({
  apiKey: 'sk-xxx123xxx', // Your API key
  baseURL: 'https://your-custom-endpoint.com' // Optional: Custom endpoint
});

Usage Examples

Basic OCR

const result = await client.scan({
  image: 'https://example.com/document.jpg'
});

console.log('Extracted text:', result.data.text);
console.log('Confidence:', result.data.confidence);
console.log('Credits remaining:', result.usage.creditsRemaining);

OCR with Base64 Image

const result = await client.scan({
  image: 'data:image/jpeg;base64,/9j/4AAQSkZJRg...',
  provider: 'google'
});

OCR with Image Description

const result = await client.scan({
  image: 'https://example.com/photo.jpg',
  provider: 'auto',
  description: true
});

console.log('Text:', result.data.text);
console.log('Description:', result.data.description);

Provider-Specific OCR

// Use Google Vision specifically
const googleResult = await client.scan({
  image: 'https://example.com/image.jpg',
  provider: 'google'
});

// Use AWS Textract for documents
const textractResult = await client.scan({
  image: 'https://example.com/document.pdf',
  provider: 'textract'
});

// Use Mistral OCR for invoices
const mistralResult = await client.scan({
  image: 'https://example.com/invoice.jpg',
  provider: 'mistral'
});

Health Check

const health = await client.health();

console.log('Status:', health.data.status);
console.log('Available providers:', health.data.providers);

Error Handling

import visr, { VisionRouterAPIError } from 'visionrouter';

try {
  const result = await client.scan({
    image: 'invalid-image-url'
  });
} catch (error) {
  if (error instanceof VisionRouterAPIError) {
    console.error('API Error:', error.code, error.message);
    console.error('Status Code:', error.statusCode);
  } else {
    console.error('Unexpected error:', error);
  }
}

API Reference

visr

Constructor

new visr(config: VisionRouterConfig)

Parameters:

• config.apiKey (string): Your Vision Router API key
• config.baseURL (string, optional): Custom API endpoint

OCR Service

scan(request, options?)

Scan an image with OCR.

Parameters:

• request.image (string): Image URL or base64 data URI
• request.provider (string, optional): OCR provider ('auto', 'google', 'textract', 'mistral', 'custom')
• request.description (boolean, optional): Whether to include image description
• options.timeout (number, optional): Request timeout in milliseconds

Returns: Promise<OCRResponse>

health()

Check API health and available providers.

Returns: Promise<HealthResponse>

Types

OCRResponse

interface OCRResponse {
  success: boolean;
  data: {
    text: string;
    description?: string;
    confidence: number;
    provider: string;
    processingTime: number;
    creditsUsed: number;
  };
  usage: {
    creditsRemaining: number;
  };
}

HealthResponse

interface HealthResponse {
  success: boolean;
  data: {
    status: string;
    providers: string[];
    timestamp: string;
  };
}

Error Handling

The library throws VisionRouterAPIError for API-related errors:

class VisionRouterAPIError extends Error {
  code: string;
  statusCode: number;
}

Common error codes:

• INVALID_IMAGE: Invalid image format or corrupted
• INVALID_API_KEY: API key not found or invalid
• INSUFFICIENT_CREDITS: User has no credits remaining
• RATE_LIMIT_EXCEEDED: Provider rate limit hit
• PROVIDER_ERROR: OCR provider error
• NETWORK_ERROR: Network connectivity issue

Provider Selection

When using provider: 'auto', the system intelligently selects the best provider based on:

• PDFs: Prefers AWS Textract
• Photos with text: Prefers Google Vision
• Documents/invoices: Prefers Mistral OCR
• Default: Google Vision

Requirements

• Node.js 14.0.0 or higher
• Active Vision Router account with API key

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: docs.visionrouter.com

License

MIT License - see LICENSE file for details.