Tinyami Node.js Client

tinyami-node is the official Node.js client for the Tinyami API – a powerful image optimization service for developers.

With this package, you can easily upload images, trigger optimization, and check optimization status via Tinyami's REST API.

🚀 Features

• Upload images to Tinyami
• Optimize, convert, resize images by ID
• Check image optimization status
• Lightweight and easy-to-use
• Written in TypeScript

🔐 Getting an API Key

To use this package, you’ll need a Tinyami API key.

1. Go to https://tinyami.com
2. Sign up or log in to your account
3. Navigate to the https://tinyami.com/api-keys section
4. Generate a new API key

Installation

npm install tinyami-api

Usage

import { TinyamiClient } from 'tinyami-api';

// Initialize the client
const client = new TinyamiClient({
  apiKey: 'your-api-key', // Your Tinyami API key
  // Optional configuration
  baseURL: 'https://api.tinyami.com', // Default
  timeout: 30000, // Default: 30 seconds
  maxRetries: 3, // Optional: Number of retry attempts
});

// Upload an image
const uploadResult = await client.uploadImage('/path/to/image.jpg');
console.log('Uploaded image ID:', uploadResult.image.id);

// Optimize the image
const optimizeResult = await client.optimizeImage(uploadResult.image.id);
console.log('Optimized image URL:', optimizeResult.optimized.preview_url);

// Check image status
const status = await client.getImageInfo(uploadResult.image.id);
console.log('Image status:', status.status);

// Delete the image
await client.deleteImage(uploadResult.image.id);

API Reference

TinyamiClient

The main client class for interacting with the Tinyami API.

Constructor

new TinyamiClient(config: TinyamiConfig)

Configuration options:

• apiKey (required): Your Tinyami API key (X-Tinyami-Access-Token)
• baseURL (optional): API base URL (default: 'https://api.tinyami.com')
• timeout (optional): Request timeout in milliseconds (default: 30000)
• maxRetries (optional): Number of retry attempts for failed requests (default: 3)

Methods

uploadImage(filePath: string): Promise

Uploads an image file to Tinyami. Supports large file uploads with proper FormData handling.

uploadImageFromUrl(url: string): Promise

Uploads an image url to Tinyami. Supports large file uploads with proper FormData handling.

optimizeImage(imageId: number): Promise

Optimizes a previously uploaded image.

getImageInfo(imageId: number): Promise

Gets the current status of an image.

deleteImage(imageId: number): Promise

Deletes an uploaded image.

getImagesList(page?: number, limit?: number): Promise

Gets a paginated list of images.

• page: Page number (default: 1)
• limit: Number of images per page (default: 20, max: 50)

convertImage(imageId: number, type: string): Promise

Converts an image to a different format.

• imageId: ID of the image to convert
• type: Target format (e.g., 'jpg', 'png', 'webp', 'avif')

resizeImage(imageId: number, method: string, width?: number, height?: number): Promise

Resizes an image using specified method and dimensions.

• imageId: ID of the image to resize
• method: Resizing method (e.g., 'scale', 'fit', 'cover', 'thumb')
• width: Target width (optional)
• height: Target height (optional)

getImageFormats(imageId: number): Promise

Gets all available formats for a specific image.

• imageId: ID of the image

getImageVariants(imageId: number): Promise

Gets all variants of a specific image.

• imageId: ID of the image

deleteImageFormat(imageId: number, formatId: string): Promise

Deletes a specific format of an image.

• imageId: ID of the image
• formatId: ID of the format to delete

Response Types

ImageUploadResponse

{
  status: string;
  msg: string;
  image: OriginalImageOut;
}

ImageOptimizeResponse

{
  msg: string;
  optimized: {
    id: number;
    original_image_id: number;
    format: string;
    size: number;
    s3_path: string;
    reduction: number;
    created_at: string;
    preview_url: string;
    download_url: string;
  }
}

ImageStatusResponse

{
  status: string;
  msg: string;
  image_info: OriginalImageOut;
}

ImageListResponse

{
  status: string;
  msg: string;
  images: OriginalImageOut[];
}

ImageConvertResponse

{
  status: string;
  msg: string;
  converted: VariantResponse;
}

ImageResizeResponse

{
  status: string;
  msg: string;
  resized: VariantResponse;
}

FormatListResponse

{
  msg: string;
  formats: FormatResponse[];
}

VariantListResponse

{
  msg: string;
  variants: VariantResponse[];
}

OriginalImageOut

{
  id: number;
  origin_name: string;
  ext: string;
  mime_type: string;
  origin_size: number;
  uid: string;
  s3_path: string;
  created_at: string;
  updated_at: string | null;
}

FormatResponse

{
  id: number;
  original_image_id: number;
  format: string;
  s3_path: string;
  size: number;
  reduction: number;
  created_at: string;
  updated_at: string | null;
}

VariantResponse

{
  id: number;
  original_image_id: number;
  variant_type: string;
  format: string | null;
  width: number | null;
  height: number | null;
  fit: string | null;
  size_bytes: number | null;
  s3_path: string;
  created_at: string;
  updated_at: string | null;
  preview_url: string | null;
  download_url: string | null;
}

Error Handling

The client throws TinyamiHttpError for API errors. You can catch and handle these errors:

try {
  await client.uploadImage('/path/to/image.jpg');
} catch (error) {
  if (error instanceof TinyamiHttpError) {
    console.error('API Error:', error.error.message);
  } else {
    console.error('Unexpected error:', error);
  }
}

Features

• Full TypeScript support
• Automatic FormData handling for file uploads
• Support for large file uploads
• Proper error handling with typed errors
• Automatic retry mechanism for failed requests
• Comprehensive API coverage

License

MIT