Picsha AI Node.js SDK

The official Node.js client for the Picsha AI API. TypeScript-first, zero runtime dependencies, works in Node 18.17+.

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
const results = await client.search("fluorescent cancer cell cultures", {
  mode: "ai", // hybrid vector search ("standard" for keyword/tag match)
});

// 2. Get transformed URLs for your app or pipeline
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

// From a file path
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 or Blob
await client.upload(imageBuffer, { filename: "sunset.jpg" });

// Ephemeral (auto-expiring) upload
await client.upload("./tmp/preview.jpg", { ephemeral: true });

Error handling

All SDK errors extend PicshaError:

import { PicshaAuthError, PicshaAPIError } from "picsha";

try {
  await client.search("query");
} catch (err) {
  if (err instanceof PicshaAuthError) {
    // Missing/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 its own type declarations — Asset, SearchResult, UploadResult, SearchOptions, UploadOptions, and friends are all exported.

License

MIT