Picsha AI

Quickstart Guide

Picsha AI allows you to instantly upload, intelligently process, and deliver media around the globe using our edge network.

1. Get an API Key

To interact with the Delivery or Upload APIs programmatically, you'll need an API key.

  1. Navigate to the API Keys tab in your dashboard.
  2. Click Generate New Key.
  3. Store this key securely. Your API key (sk_live_...) is a secret: it carries full read, write, and delete rights over your organization, so it belongs on your server only — never in browser code, a mobile bundle, or a public repo.

[!WARNING] Picsha does not currently issue a separate browser-safe "publishable" key. Any credential you hand to a browser must be either a short-lived Picsha (Clerk) session token belonging to the signed-in user, or a URL your backend has already signed. See Architecture & Concepts for the full credential model.

2. Uploading an Image

For backend uploads, push binary data to our tus resumable upload endpoint (/v1/upload/resumable), or request a presigned S3 upload URL with GET /v1/assets/presigned using your secret key.

For browser uploads, use the React SDK and supply a token from your own session — getToken is called on every request and its return value is sent as Authorization: Bearer <token>:

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

export default function MyUpload() {
  return (
    <PicshaUploadWidget
      // A Picsha (Clerk) session token for the signed-in user, or a short-lived
      // token your own backend mints. Never your sk_live_... key.
      getToken={async () => (await fetch('/api/picsha-token')).text()}
      onUploadSuccess={(asset) => console.log('Upload finished:', asset.id)}
    />
  )
}

3. Delivering the Image

Once uploaded, Picsha instantly encodes and distributes your media via CloudFront.

<img src="https://cdn.picsha.ai/render/550e8400-e29b-41d4-a716-446655440000?fit=cover&h=500&w=500" />

Any image parameters (h, w, fit) are automatically computed on the fly by our high-performance Sharp (libvips) image processors!

[!WARNING] By default, your assets are publicly deliverable. For production applications, we highly recommend enabling Strict Transformations in your organization settings. This requires cryptographic signatures (?sig=...) on your URLs, preventing malicious users from enumerating query strings or executing unauthorized generative AI edits on your assets.