Concepts

Files & Drive

Models take input assets as URLs and return results as URLs hosted on the Picsart CDN. Turn on Drive to have every generation saved to an organized, permanent folder automatically.

Input files

Any model that takes an image, video, or audio input reads it from a publicly reachable URL — for example imageUrls, videoUrl, startFrame, or audioUrl. Each model page lists the exact keys it accepts.

// Input assets are passed as public URLs — imageUrls, videoUrl,
// startFrame, endFrame, audioUrl, … depending on the model.
const result = await ai.generate('seedream-5.0-pro', {
  prompt: 'Replace the background with a snowy forest',
  imageUrls: ['https://cdn.example.com/photo.jpg'],
});

console.log(result.url);

Getting a URL for a local file. The SDK and REST API expect a URL you host (your own CDN/bucket, a signed URL, or a Picsart Drive asset). The gen-ai CLI is the shortcut: pass a local path with -i and it uploads the file and forwards the URL for you.

Output files & the CDN

Every media generation resolves to a URL on cdn.picsart.com. result.url is the primary asset; result.results holds every output (some models return several).

SDK / REST: download the URL, or save it to Drive for a permanent, organized copy (below).
CLI: results download to ./output by default — pass --no-download to print the URL only.

Auto-save to Drive

Pass a drive config to createClient and every generate() result is saved to that folder in Picsart Drive, along with the model id and the parameters that produced it. The saved file is returned on result.drive.

TypeScript

import { createClient } from '@picsart/ai-sdk';

const ai = createClient({
  apiKey: process.env.PICSART_API_KEY,
  apiUrl: 'https://api.picsart.com',
  // Enable Drive — every generation is saved to this folder.
  drive: { folder: 'AI Playground' },
});

const result = await ai.generate('flux-2-pro', {
  prompt: 'A serene mountain lake at golden hour',
});

console.log(result.url);          // CDN URL of the generated image
console.log(result.drive?.uid);   // uid of the file saved in Drive
console.log(result.drive?.folder); // { name, uid }

Override the filename or target board per call with the drive option:

TypeScript

// Override the filename and target board (subfolder) for a single call.
await ai.generate(
  'flux-2-pro',
  { prompt: 'hero banner, spring sale' },
  {
    drive: {
      name: 'spring-hero.png',
      folder: { path: 'AI Playground/Landing' },
    },
  },
);

Text generations (generateText()) return strings rather than assets and are not saved to Drive.

Working with Drive

When Drive is configured, ai.drive exposes the full folder and file surface — list assets, organize boards, save external URLs, and read back the generation metadata.

TypeScript

// ai.drive is available whenever the client is created with a `drive` config.

// List recent images across all boards
const images = await ai.drive!.list({ type: 'image' });
for (const item of images) console.log(item.name, item.url);

// The same, with full generation metadata (model, prompt, params, …)
const detailed = await ai.drive!.listDetailed({ type: 'video' });

// Organize into boards (subfolders under the root folder)
const board = await ai.drive!.ensureFolder('Campaign Q3');

// Save an existing asset (by URL) straight into Drive
await ai.drive!.save(
  {
    url: 'https://cdn.example.com/asset.png',
    name: 'asset.png',
    resourceType: 'PHOTO',
  },
  board ?? undefined,
);

// Read back what produced a generation
const gen = await ai.drive!.getGeneration(images[0].uid);
console.log(gen?.model, gen?.aiSDKPayload?.prompt);

Image generation →

Text-to-image, editing, and reference images.

Explore models →

See the exact input keys each model accepts.