Node.js SDK

The official picsha Node.js SDK is a TypeScript-first client for the Picsha AI API. It has zero runtime dependencies, ships its own type declarations, and works in any Node.js 18.17+ project (both ESM and CommonJS).

Installation

npm install picsha

Quickstart

import { Client } from "picsha";

const client = new Client({ apiKey: "sk_your_key_here" });
// Or set the PICSHA_API_KEY environment variable and call new Client()

// 1. Semantic search across your assets
const results = await client.search("sunset over mountains", {
  mode: "ai", // hybrid vector search ("standard" for keyword/tag match)
});

// 2. Build on-the-fly transformation URLs for your app
for (const asset of results.assets) {
  const url = client.transformUrl(asset, { width: 512, height: 512, format: "webp" });
  console.log(url);
}

console.log(`Found ${results.totalCount} assets (more pages: ${results.hasMore})`);

Uploading Assets

Upload from a file path, Buffer, or Blob:

// From a file path, with tags and metadata
const uploaded = await client.upload("./photos/sunset.jpg", {
  tags: ["landscape", "golden-hour"],
  metadata: { shoot: "iceland-2026" },
});
console.log(uploaded.id, uploaded.url);

// From a Buffer (e.g. an incoming request body)
await client.upload(imageBuffer, { filename: "sunset.jpg" });

// Ephemeral upload: the asset expires automatically
await client.upload("./tmp/preview.jpg", { ephemeral: true });

Every upload is queued for the full ingest pipeline: metadata extraction, AI analysis, vector embedding, and search indexing happen automatically within moments.

Error Handling

All SDK errors extend PicshaError, so failures are easy to route:

import { PicshaAuthError, PicshaAPIError } from "picsha";

try {
  await client.search("query");
} catch (err) {
  if (err instanceof PicshaAuthError) {
    // Missing or invalid API key, or insufficient permissions (401/403)
  } else if (err instanceof PicshaAPIError) {
    console.error(err.statusCode, err.details);
  }
}

Configuration

const client = new Client({
  apiKey: "sk_...",                    // or PICSHA_API_KEY env var
  baseUrl: "https://api.picsha.ai/v1", // default
  timeoutMs: 60_000,                   // default; raise for very large uploads
});

TypeScript

The package ships full type declarations: Asset, SearchResult, UploadResult, SearchOptions, UploadOptions, and TransformOptions are all exported, so you get autocomplete and compile-time checking with no extra @types package.

Key Use Cases

• Product search in your storefront: wire client.search(query, { mode: "ai" }) to a search box and let customers find assets by describing them in natural language.
• Serverless ingestion: the SDK's zero-dependency footprint keeps Lambda and edge bundles small; upload straight from a Buffer without touching disk.
• Responsive delivery: generate transformUrl variants (width, format, quality) per breakpoint and let the Picsha edge do the resizing.