SDKs
The @pichaflow/sdk provides a programmatic way to interact with the PichaFlow API.
Initialization
import { PichaFlowClient } from '@pichaflow/sdk';
const client = new PichaFlowClient({
apiKey: 'sk_live_your_secret_key',
baseUrl: 'https://api.pichaflow.com' // Optional
});
Built-in Auto-Optimization
By default, the @pichaflow/sdk and all framework UI plugins (@pichaflow/react, @pichaflow/vue, etc.) automatically perform Client-Side Pre-Optimization.
If a user uploads a massive 24 Megapixel master image, the SDK intercepts the file, uses the browser's native HTML5 Canvas API to strictly scale the longest edge down to 2048px (maintaining aspect ratio), and natively exports it as a highly compressed image/webp file. This happens instantly in the browser before the network request begins, ensuring blazing-fast uploads and zero API limits exceeded.
Uploading Images (Server-Side)
When operating from a trusted backend environment (e.g., Node.js, Cloudflare Workers), use your sk_live_ secret key for direct, zero-friction uploads.
const file = // ... from a file input
const response = await client.upload(file, {
directory: 'products/hero',
tags: ['ecommerce', 'boots'],
onProgress: (p) => console.log(`Upload progress: ${p}%`)
});
console.log('Asset ID:', response.id);
413 Payload Too Large error to prevent Out-Of-Memory (OOM) decompression bombs on the edge network.directory path becomes part of the asset's permanent delivery URL. You cannot move assets between directories after upload — doing so would break any live links embedding the URL.Secure Client Uploads (HMAC Handshake)
When uploading directly from a user's browser, you must never expose your sk_live_ secret key. Instead, initialize the client without configuring the apiKey property, and use the secureUpload() method.
This initiates an HMAC-SHA256 handshake. The SDK will make a request to your backend proxy (signatureUrl) to fetch a temporary, 60-second signature, before transmitting the file directly to the PichaFlow Engine. This keeps your secret key safe on your backend while securing client-side uploads.
// 1. Initialize PichaFlowClient without an apiKey
const client = new PichaFlowClient();
// 2. Use secureUpload with your backend proxy signatureUrl
const file = // ... from an input
const response = await client.secureUpload(
file,
{
// Point this to your backend endpoint that proxies the signature request
signatureUrl: '/api/my-backend/sign-upload',
directory: 'ugc/avatars',
tags: ['ugc', 'avatar']
}
);
Delivery URLs
Generate optimized CDN URLs on the fly.
// Asset at project root
const rootUrl = client.getDeliveryUrl('image.jpg', {
w: 800,
q: 80,
f: 'webp'
});
// Asset inside a directory
const dirUrl = client.getDeliveryUrl('products/hero/image.jpg', {
w: 800,
q: 80,
f: 'webp'
});
Unpic Integration
The SDK exposes a custom provider for the universal responsive image component library Unpic. You can use this to easily generate responsive images using standard layouts (srcset and sizes) automatically handled by PichaFlow's CDN.
Programmatic Usage
You can import unpicProvider to programmatically transform or parse URLs.
import { unpicProvider } from '@pichaflow/sdk';
// 1. Transform a PichaFlow URL
const url = unpicProvider.transform('https://cdn.pichaflow.com/user/avatar.png', {
width: 400,
height: 400,
format: 'webp',
quality: 85
});
// 2. Extract properties from an existing PichaFlow URL
const data = unpicProvider.extract('https://cdn.pichaflow.com/user/avatar.png?w=400');
console.log(data?.operations.width); // 400
Component Integration (e.g. React)
Pass unpicProvider.transform directly to the transformer prop of Unpic's <Image> components:
import { Image } from '@unpic/react';
import { unpicProvider } from '@pichaflow/sdk';
export const ProductHero = () => (
<Image
src="https://cdn.pichaflow.com/products/hero.png"
width={800}
height={600}
alt="Product Hero"
transformer={unpicProvider.transform}
/>
);