JSTextFromImage

A powerful TypeScript/JavaScript library for obtaining detailed descriptions of images using various AI models including OpenAI's GPT-4 Vision, Azure OpenAI, and Anthropic Claude. Supports image URLs with batch processing capabilities.

🌟 Key Features

• 🤖 Multiple AI Providers: Support for OpenAI, Azure OpenAI, and Anthropic Claude
• 🌐 URL Support: Process images from URLs
• 📦 Batch Processing: Process multiple images concurrently
• 📝 TypeScript First: Built with TypeScript for excellent type safety
• 🔄 Async/Await: Modern Promise-based API
• 🔑 Flexible Auth: Multiple authentication methods including environment variables
• 🛡️ Error Handling: Comprehensive error handling

📦 Installation

npm install jstextfromimage

🚀 Quick Start

You can use the services either with environment variables or direct initialization.

Using Environment Variables

import { openai, claude, azureOpenai } from 'jstextfromimage';

// Services will automatically use environment variables
const description = await openai.getDescription('https://example.com/image.jpg');

Direct Initialization

import { OpenAIService, ClaudeService, AzureOpenAIService } from 'jstextfromimage';

// OpenAI custom instance
const customOpenAI = new OpenAIService('your-openai-api-key');

// Claude custom instance
const customClaude = new ClaudeService('your-claude-api-key');

// Azure OpenAI custom instance
const customAzure = new AzureOpenAIService({
 apiKey: 'your-azure-api-key',
 endpoint: 'your-azure-endpoint',
 deploymentName: 'your-deployment-name'
});

OpenAI Service

import { openai } from 'jstextfromimage';

// Single image analysis
const description = await openai.getDescription('https://example.com/image.jpg', {
 prompt: "Describe the main elements of this image",
 maxTokens: 500,
 model: 'gpt-4o'
});

// Batch processing
const imageUrls = [
 'https://example.com/image1.jpg',
 'https://example.com/image2.jpg',
 'https://example.com/image3.jpg'
];

const results = await openai.getDescriptionBatch(imageUrls, {
 prompt: "Analyze this image in detail",
 maxTokens: 300,
 concurrency: 2,
 model: 'gpt-4o'
});

// Process results
results.forEach(result => {
 if (result.error) {
 console.error(`Error processing ${result.imageUrl}: ${result.error}`);
 } else {
 console.log(`Description for ${result.imageUrl}: ${result.description}`);
 }
});

Claude Service

import { claude } from 'jstextfromimage';

// Single image analysis
const description = await claude.getDescription('https://example.com/artwork.jpg', {
 prompt: "Analyze this artwork, including style and composition",
 maxTokens: 1000,
 model: 'claude-3-sonnet-20240229'
});

// Batch processing
const artworkUrls = [
 'https://example.com/artwork1.jpg',
 'https://example.com/artwork2.jpg'
];

const analyses = await claude.getDescriptionBatch(artworkUrls, {
 prompt: "Provide a detailed art analysis",
 maxTokens: 800,
 concurrency: 2,
 model: 'claude-3-sonnet-20240229'
});

Azure OpenAI Service

import { azureOpenai } from 'jstextfromimage';

// Single image analysis
const description = await azureOpenai.getDescription('https://example.com/scene.jpg', {
 prompt: "Describe this scene in detail",
 maxTokens: 400,
 systemPrompt: "You are an expert in visual analysis."
});

// Batch processing
const sceneUrls = [
 'https://example.com/scene1.jpg',
 'https://example.com/scene2.jpg'
];

const analyses = await azureOpenai.getDescriptionBatch(sceneUrls, {
 prompt: "Analyze the composition and mood",
 maxTokens: 500,
 concurrency: 3,
 systemPrompt: "You are an expert cinematographer."
});

💡 Configuration

Default Values

// OpenAI defaults
{
 model: 'gpt-4o',
 maxTokens: 300,
 prompt: "What's in this image?",
 concurrency: 3 // for batch processing
}

// Claude defaults
{
 model: 'claude-3-sonnet-20240229',
 maxTokens: 300,
 prompt: "What's in this image?",
 concurrency: 3
}

// Azure OpenAI defaults
{
 maxTokens: 300,
 prompt: "What's in this image?",
 systemPrompt: "You are a helpful assistant.",
 concurrency: 3
}

Local File Support

import { openai } from 'jstextfromimage';

// Single local file
const description = await openai.getDescription('/path/to/local/image.jpg', {
 prompt: "Describe this image",
 maxTokens: 300,
 model: 'gpt-4o'
});

// Mix of local files and URLs in batch processing
const images = [
 '/path/to/local/image1.jpg',
 'https://example.com/image2.jpg',
 '/path/to/local/image3.png'
];

const results = await openai.getDescriptionBatch(images, {
 prompt: "Analyze each image",
 maxTokens: 300,
 concurrency: 2
});

Environment Variables

# OpenAI
OPENAI_API_KEY=your-openai-api-key

# Claude
ANTHROPIC_API_KEY=your-claude-api-key

# Azure OpenAI
AZURE_OPENAI_API_KEY=your-azure-api-key
AZURE_OPENAI_ENDPOINT=your-azure-endpoint
AZURE_OPENAI_DEPLOYMENT=your-deployment-name

Options Interfaces

// Base options for all services
interface BaseOptions {
 prompt?: string;
 maxTokens?: number;
 concurrency?: number; // For batch processing
}

// OpenAI specific options
interface OpenAIOptions extends BaseOptions {
 model?: string;
}

// Claude specific options
interface ClaudeOptions extends BaseOptions {
 model?: string;
}

// Azure OpenAI specific options
interface AzureOpenAIOptions extends BaseOptions {
 systemPrompt?: string;
}

// Azure OpenAI configuration
interface AzureOpenAIConfig {
 apiKey?: string;
 endpoint?: string;
 deploymentName?: string;
 apiVersion?: string;
}

// Batch processing results
interface BatchResult {
 imageUrl: string;
 description: string;
 error?: string;
}

🔍 Error Handling Examples

// Single image with error handling
try {
 const description = await openai.getDescription(imageUrl, {
 maxTokens: 300
 });
 console.log(description);
} catch (error) {
 console.error('Failed to process image:', error);
}

// Batch processing with retry
async function processWithRetry(imageUrls: string[], maxRetries = 3) {
 const results = await openai.getDescriptionBatch(imageUrls, {
 maxTokens: 300,
 concurrency: 2
 });
 
 // Handle failed items with retry
 const failedItems = results.filter(r => r.error);
 let retryCount = 0;
 
 while (failedItems.length > 0 && retryCount < maxRetries) {
 const retryUrls = failedItems.map(item => item.imageUrl);
 const retryResults = await openai.getDescriptionBatch(retryUrls, {
 maxTokens: 300,
 concurrency: 1 // Lower concurrency for retries
 });
 
 // Update results with successful retries
 retryResults.forEach(result => {
 if (!result.error) {
 const index = results.findIndex(r => r.imageUrl === result.imageUrl);
 if (index !== -1) {
 results[index] = result;
 }
 }
 });
 
 retryCount++;
 }
 
 return results;
}

🛠️ Development

# Install dependencies
npm install

# Run tests
npm test

# Build the project
npm run build

# Run linting
npm run lint

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

For support, please open an issue on GitHub.