📸 PichaX SDK (Node.js)

The official Node.js SDK for interacting with the PichaX image transformation and identicon generation service.

Generate signed, expirable image URLs for transformations such as rotate, resize, flip, and identicons — fast, secure, and simple.

🚀 Installation

npm install @chakata/pichax
# or
yarn add pichax

Example

import { PichaX } from '@chakata/pichax';

const picha = new PichaX('your_api_key', 'your_api_secret');


// 🔁 Transform an image
const transformUrl = picha.transform({
  id: 'img_123',
  expires: '1725168000', // Unix timestamp
  src: 'https://example.com/image.jpg',
  cache: false, // Not required. Default: true
  params: {
    "rotate": {"degrees": 45},
    "resize": {"w": 100, "h": 200, "mode": "fill"}, // Modes: "fit", "fill", "crop"
    // Resize options:
    // {"scale": 0.5} -- This will scale image to 50% of the original size
    // {"w": 100} -- This will keep aspect ratio
    "effects": [{"grayscale": true}, {"blur": 10}, {"sharpen": true}],
    "format": "jpeg", // Options are: "webp", "jpeg", "png"
    "quality": 80, // 0 - 100
    "watermark": {"text": "Hello there"},
    // custom watermarks are only supported in production key
    // a default watermark is applied otherwise
    "crop": {"x": 100,"y": 30,"w": 100,"h": 20}
    // Crop options:
    // {"w": 100, "h", 200, "mode": "centre"} -- Modes: "centre", "attention", "entropy"
  }
}).getUrl();

console.log(transformUrl);

// 👤 Generate an identicon
const identiconUrl = picha.identicon({
  id: 'user_123',
  expires: '1725168000',
  name: 'PichaX'
}).getUrl();

console.log(identiconUrl);

🔐 Signature Generation

All URLs include a signature for security, generated using HMAC-SHA256:

HMAC_SHA256(unique_key + ":" + expires, api_secret)

🧰 Transformations

Each transformation is optional and can be combined:

params: {
  rotate: { degrees: 90 },              // 0 - 360
  resize: { scale: 0.5 },               // 0 < scale <= 1
  flip: { direction: 'horizontal' },    // 'horizontal' | 'vertical'
  grayscale: true,
  crop: {x: 100, y: 100, w: 200, h: 300}, // x and y are optional and will default to 0
  // crop: { type: "frontal_face" } Uses AI to detect front looking face
}

Crop

crop is a bit special. If { type: 'frontal_face' } is used, PichaX uses AI to detect a frontal looking face and crops by it. This feature is experimental and we are improving it every day.

✅ Type Safety

This SDK is written in TypeScript and includes full type definitions out of the box.

Testing

npm test

🌐 Learn More

For full API documentation, visit Docs