Interfaces
SDK
@picsart/ai-sdk is the type-safe TypeScript SDK for all 169+ models. One client, one call — the SDK validates parameters, transforms them to each model's payload, and waits for the result. It's the recommended way to call Picsart from a Node or TypeScript app.
Install
npm install @picsart/ai-sdk- Node.js 20 or newer — the SDK is ESM-only and ships with full TypeScript types.
- A Picsart API key — see Authentication.
Generate
Create a client once, then call any model by id. generate() is model-aware — parameters autocomplete per model — and returns a GenerateResult.
import { createClient } from '@picsart/ai-sdk';
const ai = createClient({
apiKey: process.env.PICSART_API_KEY,
apiUrl: 'https://api.picsart.com',
});
// Media models return URLs…
const image = await ai.generate('flux-2-pro', {
prompt: 'A serene mountain lake at golden hour',
aspectRatio: '16:9',
});
console.log(image.url);
// …text models return strings.
const { text } = await ai.generateText('claude-opus-4-8', {
prompt: 'Write a haiku about the sea.',
});
console.log(text);Direct API — apis.run()
Beneath generate() is a lower-level client. ai.apis.run() calls any workflow by name and forwards your payload as-is — no parameter transformation — while still hiding polling and streaming behind a simple await. Reach for it when you want direct control, or to run utility workflows that aren't in the model catalog.
| Aspect | generate() | apis.run() |
|---|---|---|
| Identifier | model id (e.g. flux-2-pro) | workflow name (e.g. flux-v2) |
| Params | validated & transformed to the vendor payload | forwarded verbatim |
| Returns | GenerateResult (url, results, …) | { result, usage } |
| Best for | the fast path — type-safe, model-aware, Drive-aware | direct control & any workflow (incl. utility ones) |
Pass the workflow name (shown on each model page), the params, and a mode. Known workflows are typed against the SDK's workflow registry.
import { createClient, ApiRunMode } from '@picsart/ai-sdk';
const ai = createClient({
apiKey: process.env.PICSART_API_KEY,
apiUrl: 'https://api.picsart.com',
});
// Call a workflow by name — params are forwarded verbatim (no transformation).
const { result, usage } = await ai.apis.run('flux-v2', {
prompt: 'A serene mountain lake at golden hour',
model: 'flux-2-pro',
}, {
mode: ApiRunMode.SYNC,
});
console.log(result); // workflow-specific output, e.g. { url: '…' }
console.log(usage?.credits); // credits chargedExecution modes
ApiRunMode selects sync, async, or streamed execution. In every case you just await a { result, usage } — the SDK handles submit/poll internally.
// mode controls how the call executes — polling/streaming stay hidden,
// you always just await the result.
await ai.apis.run('kling-text-to-video', params, { mode: ApiRunMode.SYNC }); // one request (≤ ~20s)
await ai.apis.run('kling-text-to-video', params, { mode: ApiRunMode.ASYNC }); // submit + poll under the hood
await ai.apis.run('kling-text-to-video', params, { mode: ApiRunMode.STREAM }); // streamed executionai.runWorkflow() is deprecated — use ai.apis.run(). Prefer raw HTTP? The same workflows are documented in the REST API.
Long-running jobs
generate() blocks until the result is ready. For slower media like video, use submit() + result() to control polling yourself — see the Quickstart.