npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2025 – Pkg Stats / Ryan Hefner

jstextfromimage

v1.1.7

Published

Get descriptions of images from OpenAI, Azure OpenAI and Anthropic Claude models. Supports both URLs and local files with batch processing capabilities.

Downloads

88

Readme

JSTextFromImage

npm Version TypeScript License Downloads Node Version

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.