Picsha.ai React SDK (`@picsha-ai/react`)

Overview

The strictly-typed React SDK provides ready-to-use components for securely uploading files to the Picsha AI backend and rendering assets with dynamic AI transformations.

Installation

npm install @picsha-ai/react

Components

1. `<PicshaImage />`

A drop-in replacement for the standard <img> tag that automatically constructs delivery URLs and applies on-the-fly transformations via the Picsha backend.

Key Features:

Typed Transformations: Pass transformations as native React props (blur={5}, radius="max").
AI-Powered Effects: Supports removeBackground, generativeRemove, and automatic aspectRatio cropping.
Overlays: Supports complex arrays of text and image overlays, automatically encoding them into the delivery URL.

Usage:

import { PicshaImage } from '@picsha-ai/react';

<PicshaImage
  deliveryEndpoint="https://cdn.picsha.ai"
  assetId="550e8400-e29b-41d4-a716-446655440000"
  width={800}
  aspectRatio="16:9"
  position="attention"
  radius={16}
  overlays={[
    { type: 'text', text: 'Stunning Event', gravity: 'bottom', size: 48 }
  ]}
/>

Props:

deliveryEndpoint (string): Base API URL
assetId (string) or url (string): The asset to render or external URL to proxy mapping to /v1/fetch
width, height, aspectRatio (number | string): Dimensions
blur, radius: Styling adjustments
format (including "auto"), quality, fit, crop, position, background: Standard image optimizations
removeBackground (boolean), generativeRemove (string): AI capabilities
mimi (string): Natural-language generative edit prompt (MIMI)
mimiMode ('lite' | 'standard' | '4k'): MIMI quality tier (default standard)
upscale ('2k' | '4k'): Free preview-faithful export upscale, one tier up
mimiBg (string): Generative background swap prompt (subject preserved pixel-exact)
overlays (OverlayConfig[]): Array of text/image layers to composite
force (boolean): Bypasses CDN cache
cb (string): Cache-busting parameter
sig (string): Delivery signature for generative props — see below
signedUrl (string): A complete pre-signed delivery URL, rendered as-is (all other transformation props are ignored)

Authorization for generative props (v2.1+)

Billed generative parameters (mimi, mimiBg, generativeRemove, removeBackground) are rejected with 401 when requested anonymously — a browser <img> cannot carry your API key, and it never should. Plain transformation props (dimensions, crop, format, quality, overlays) work anonymously as before. Two ways to render generative images on public pages:

Option A — signedUrl (simplest): call POST /assets/{id}/sign-delivery server-side and hand the resulting URL to the component untouched:

<PicshaImage signedUrl={signedUrlFromYourApi} alt="Generated scene" />

Option B — sig + matching props: the signature covers the exact query permutation, so build it server-side from the same props using the exported buildPicshaQueryParams helper:

// server
import { buildPicshaQueryParams } from '@picsha-ai/react';
const queryParams = buildPicshaQueryParams({ width: 800, mimi: 'golden hour' });
const { signature } = await picshaPost(`/assets/${id}/sign-delivery`, {
  urlPath: `/v1/assets/${id}/render`, queryParams,
});

// client — props MUST match what was signed, or the CDN refuses the request
<PicshaImage deliveryEndpoint="..." assetId={id} width={800} mimi="golden hour" sig={signature} />

The url prop proxies through /v1/fetch, which now requires authentication (it was hardened against server-side request forgery). It can no longer be used from the browser — ingest external URLs into Picsha server-side instead. The component logs a console warning when it is used.

2. `<PicshaUploadWidget />`

A robust, themeable upload widget built on top of Uppy. It automatically handles secure authentication, direct-to-S3 uploads, and post-upload registration with the Picsha AI backend.

Key Features:

Secure Integration: Automatically requests signed URLs via /v1/assets/presigned before uploading to S3.
Resumable Uploads: Pass useResumable={true} to activate the Tus protocol for robust chunked uploads for large assets.
Auto-Registration: After a successful upload, seamlessly calls POST /v1/assets to finalize the asset directly from the client.

Usage:

import { PicshaUploadWidget } from '@picsha-ai/react';

<PicshaUploadWidget
  apiUrl="https://api.picsha.ai"
  getToken={async () => (await fetch('/api/picsha-token')).text()}
  useResumable={true}
  maxFileSize={1024 * 1024 * 1024} // 1GB (default is 2GB)
  theme="dark"
  onUploadSuccess={(asset) => console.log('Asset ready:', asset)}
/>

Tracking upload state:

const [uploading, setUploading] = useState(false);

<PicshaUploadWidget
  apiUrl="https://api.picsha.ai"
  getToken={async () => (await fetch('/api/picsha-token')).text()}
  onIsUploadingChange={setUploading}
  onUploadSuccess={(asset) => console.log('Asset ready:', asset)}
/>

false means the files have finished uploading, whether or not every file succeeded. It can arrive more than once for the same batch, so treat the value as state rather than counting calls. onUploadSuccess fires separately for each file once it is registered with Picsha, which can be a moment after false.