Picsha AI

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)}
/>

Props:

  • apiUrl (string): Base API URL
  • getToken (async function): Returns the credential sent as Authorization: Bearer <token> on every upload request. Use a Picsha session token for the signed-in user, or a short-lived token your own backend mints. Never your sk_live_... secret key — it grants full delete rights over the organization and there is no browser-safe publishable key (see Architecture & Concepts).
  • useResumable (boolean): Activates the TUS protocol for large files instead of standard presigned puts
  • onUploadSuccess (function): Callback with full asset details once registered
  • onError (function): Error handling callback
  • maxFileSize (number): Limit maximum bytes allowed (default 2GB)
  • theme ('light' | 'dark' | 'auto'): Widget theme
  • orgId (string): Optional Organization tag