@picsart/ai-sdk 1.152.1 → 3.17.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Picsart, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# @picsart/ai-sdk
+
+Generate images, videos, and audio with 100+ AI models.
+
+## Documentation
+
+Interactive guides deployed via GitLab Pages:
+
+- [SDK Guide](https://picsart.gitlab.io/web/miniapp-projects/ai-toolkit/sdk_guide.html) -- Usage examples, client setup, model registry, Drive integration, and full API reference
+- [CLI Guide](https://picsart.gitlab.io/web/miniapp-projects/ai-toolkit/cli_guide.html) -- Commands, flags, interactive mode, scripting, batch processing, and troubleshooting
+
+Source: [`sdk_guide.html`](sdk_guide.html)
+
+Repository: [gitlab.com/picsart/backend/Editor/external-ai-integrations/pa-gen-ai-sdk](https://gitlab.com/picsart/backend/Editor/external-ai-integrations/pa-gen-ai-sdk)
+
+## Quick Start
+
+```bash
+npm install @picsart/ai-sdk
+```
+
+```typescript
+import { createClient, Models, Model, catalog } from '@picsart/ai-sdk'
+
+// Create a client — pass your authenticated fetch
+const ai = createClient({
+  fetch: myAuthenticatedFetch,
+  apiUrl: 'https://api.picsart.com',
+})
+
+// Generate (Models.* are typed model-id constants)
+const result = await ai.generate(Models.Flux2Pro, { prompt: 'a cat on mars' })
+console.log(result.url)
+
+// Browse models — the `catalog` accessor
+catalog.all()                              // every model
+catalog.find({ output: 'video' })          // video models only
+catalog.search('kling')                    // search by name/id/provider
+
+// Model metadata & params — the `Model` accessor
+Model(Models.Flux2Pro).name                // 'Flux 2 Pro'
+Model(Models.Flux2Pro).meta()              // mode, provider, badges, …
+Model(Models.Flux2Pro).params()            // accepted parameters
+Model(Models.Flux2Pro).params().toSchema() // param schema
+
+// Validate input (never throws) → { valid, errors? }
+Model(Models.Flux2Pro).validate({ prompt: 'a cat' })
+```
+
+## Drive Integration
+
+Auto-save generations to Picsart Drive:
+
+```typescript
+const ai = createClient({
+  fetch: myAuthenticatedFetch,
+  apiUrl: 'https://api.picsart.com',
+  drive: { folder: 'AI Playground' },
+})
+
+// Generates and auto-saves to the root folder
+const result = await ai.generate(Models.Flux2Pro, { prompt: 'a cat' })
+// result.drive = { uid: '...', folder: { name: 'AI Playground', uid: '...' } }
+
+// Save to a subfolder
+const board = await ai.drive.ensureFolder('Cats')
+const result = await ai.generate(Models.Flux2Pro, { prompt: 'a cat' }, { folder: board })
+
+// Browse Drive
+const folders = await ai.drive.folders()
+const items = await ai.drive.list()
+```
+
+## Text Generation (LLMs)
+
+Claude, GPT, and Gemini text models are called with `generateText()`. Single-shot:
+pass a prompt and optional image(s)/video, get text back. They surface in the catalog
+as `mode: 'text'`. Each vendor uses its own native workflow, so capabilities aren't lost
+— Gemini accepts video input, Claude uses the Anthropic-native messages API.
+
+```typescript
+import { createClient, Models } from '@picsart/ai-sdk'
+
+const ai = createClient({ fetch: myAuthenticatedFetch, apiUrl: 'https://api.picsart.com' })
+
+// Text in, text out
+const { text } = await ai.generateText(Models.ClaudeOpus48, { prompt: 'Explain RAG in one line.' })
+console.log(text)
+
+// Optional vision input + reasoning level (OpenAI / Gemini)
+const res = await ai.generateText(Models.Gpt55, {
+  prompt: 'What is in this image?',
+  imageUrls: ['https://cdn.example.com/photo.jpg'],
+  thinking: 'high',            // 'off' | 'low' | 'medium' | 'high'
+})
+console.log(res.text)
+console.log(res.raw)            // full backend response — usage, finish_reason, etc.
+
+// Gemini accepts video input
+await ai.generateText(Models.Gemini3Pro, {
+  prompt: 'Summarize this clip',
+  videoUrl: 'https://cdn.example.com/clip.mp4',
+})
+
+// Browse text models
+catalog.find({ output: 'text' })
+```
+
+> Thinking level maps per vendor: OpenAI → `reasoning_effort`, Gemini →
+> `thinkingConfig.thinkingLevel` (LOW/HIGH). Claude’s `claude/v1/messages`
+> workflow exposes no thinking knob, so Claude models omit `thinking`.
+
+`generateText()` is type-narrowed to text models (`TextModelId`); calling it with an
+image/video model throws, and `generate()` throws on a text model — use the matching
+method for each.
+
+## Advanced Lifecycle
+
+For progress tracking, cancellation, and job recovery:
+
+```typescript
+// Submit without waiting
+const handle = await ai.submit(Models.KlingV3Pro, { prompt: 'a sunset' })
+
+// Subscribe to status updates
+for await (const update of ai.subscribe(handle)) {
+  console.log(update.status, update.progress?.percent)
+}
+
+// Or poll manually
+const status = await ai.status(handle)
+```
+
+## Public API
+
+The SDK exports 7 symbols:
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `createClient` | function | Create an AI client from authenticated fetch |
+| `Models` | object | Model catalog: 108 models + list/search/validate/toSchema |
+| `GenerateResult` | type | `{ url, model, handle, drive? }` |
+| `ClientConfig` | type | `{ fetch, apiUrl, drive? }` |
+| `AuthenticatedFetch` | type | `(url, init?) => Promise<Response>` |
+| `SdkTransport` | type | Advanced: custom transport interface |
+| `WorkflowJobHandle` | type | Job handle for submit/status/cancel |
+
+## Package Structure
+
+```
+packages/ai-sdk/
+  package.json
+  tsconfig.json
+  tsup.config.ts
+  src/
+    index.ts                    # Public API entry (7 exports)
+    client/
+      types.ts                  # ClientConfig, GenerateResult, DriveConfig
+      transport.ts              # Authenticated fetch → SdkTransport
+      prepare.ts                # Validate input, build payload, parse result
+      drive.ts                  # Drive folder management + file saving
+      index.ts                  # createClient() factory
+    core/
+      types.ts                  # ModelDefinition, ParamConfig, GenerationContext
+      workflow.ts               # Generic polling/execution engine
+      contracts.ts              # Runtime input validation
+      schema.ts                 # ParamConfig → JSON Schema
+      response.ts               # Vendor-agnostic result extraction
+      pricing.ts                # ToolId resolution
+      model-registry.ts         # Model lookup indexes
+      providers.ts              # Provider colors, labels, names
+      voices.ts                 # Voice catalogs (ElevenLabs, OpenAI, Gemini)
+      helpers.ts                # Vendor utilities
+    generated/
+      model-constants.ts        # AUTO-GENERATED: Models object + 108 constants
+      model-input-types.ts      # AUTO-GENERATED: per-model TypeScript input types
+    vendors/
+      define.ts                 # defineModels() framework + params.* helpers
+      presets.ts                # Reusable paramConfig factories
+      catalog/
+        index.ts                # Aggregation: ALL_MODELS, VENDOR_CATALOGS
+        kling.ts                # One file per vendor (31 total)
+        flux.ts
+        ...
+  __tests__/                    # SDK tests
+  scripts/                      # Build scripts
+```
+
+## Adding a New Model
+
+### Standard flow (pass-through payload)
+
+When the backend accepts param values as-is (no field renaming needed):
+
+1. Add config in `src/vendors/catalog/{vendor}.ts` via `defineModels()`:
+   - `buildPayload` is **optional** — omit it and param values pass through as-is
+2. Run `npm run build:model-constants` to regenerate constants
+3. Run `npm run build:model-input-types` to regenerate TypeScript types
+4. Model automatically appears in `catalog.all()` and as the `Models.NewModel` id constant
+
+### With payload transforms
+
+When the vendor API uses different field names or value formats:
+
+1. Define the model config as above (no `buildPayload`)
+2. Run `npm run build:model-input-types` — generates typed input for your model
+3. Create `src/vendors/catalog/{vendor}.payloads.ts`:
+   ```ts
+   import type { ModelInput } from '../../generated/model-input-types.ts';
+   import { registerPayloads } from '../define.ts';
+   import { SPECS, MODELS } from './{vendor}.ts';
+
+   registerPayloads({ SPECS, MODELS }, {
+     'model-id': (input: ModelInput<'model-id'>) => ({
+       prompt: input.prompt,
+       aspect_ratio: input.aspectRatio,  // rename for vendor API
+     }),
+   });
+   ```
+4. Import the `.payloads.ts` file in `src/vendors/catalog/index.ts` (after the vendor import)
+
+See `src/vendors/catalog/imagen.ts` + `src/vendors/catalog/imagen.payloads.ts` for a working example.

package/_vendor/pa-model-pricing-sdk/index.d.ts

@@ -0,0 +1,6 @@
+import { ModelPricingClient } from './lib/ModelPricingClient';
+import { ModelPricingClientError } from './lib/errors/ModelPricingClientError';
+import { ModelPricingServerError } from './lib/errors/ModelPricingServerError';
+import { ModelPricingUnknownError } from './lib/errors/ModelPricingUnknownError';
+import { UseCase, PricingUnit, ModelPricingFilters, ModelPricingMetadata, SkuEntry, VendorCostEntry, ModelPricing, ModelPricingListResponse, ModelPricingClientOptions } from './lib/types';
+export { ModelPricingClient, ModelPricingClientError, ModelPricingServerError, ModelPricingUnknownError, UseCase, PricingUnit, ModelPricingFilters, ModelPricingMetadata, SkuEntry, VendorCostEntry, ModelPricing, ModelPricingListResponse, ModelPricingClientOptions, };

package/_vendor/pa-model-pricing-sdk/lib/ModelPricingClient.d.ts

@@ -0,0 +1,30 @@
+import { ModelPricingClientOptions, ModelPricingFilters, ModelPricing } from './types';
+export declare class ModelPricingClient {
+    private readonly options;
+    private readonly modelPricingApiBaseUrl;
+    private pricing;
+    private refreshTimer;
+    private readonly defaultHeaders;
+    constructor(options: ModelPricingClientOptions);
+    /**
+     * Loads pricing data and starts the periodic refresh scheduler.
+     * Must be called and awaited before getModelPricing.
+     */
+    init(): Promise<void>;
+    /**
+     * Stops the periodic refresh scheduler.
+     */
+    stop(): void;
+    /**
+     * Returns model pricings matching the given filters from the in-memory cache.
+     * Throws if pricing has not been loaded yet — call and await init() first.
+     */
+    getModelPricing(filters?: ModelPricingFilters): ModelPricing[];
+    private loadAll;
+    private applyFilters;
+    private toSuccessResponse;
+    private throwIfError;
+    private wrapError;
+    private buildRequestHeaders;
+    private _fetch;
+}

package/_vendor/pa-model-pricing-sdk/lib/errors/ModelPricingClientError.d.ts

@@ -0,0 +1,5 @@
+export declare class ModelPricingClientError extends Error {
+    status: number;
+    details: unknown;
+    constructor(action: string, status: number, responseBody: unknown);
+}

package/_vendor/pa-model-pricing-sdk/lib/errors/ModelPricingServerError.d.ts

@@ -0,0 +1,3 @@
+export declare class ModelPricingServerError extends Error {
+    constructor(message: string);
+}

package/_vendor/pa-model-pricing-sdk/lib/errors/ModelPricingUnknownError.d.ts

@@ -0,0 +1,3 @@
+export declare class ModelPricingUnknownError extends Error {
+    constructor(message: string);
+}

package/_vendor/pa-model-pricing-sdk/lib/types.d.ts

@@ -0,0 +1,94 @@
+export declare enum UseCase {
+    TextToImage = "text-to-image",
+    ImageToImage = "image-to-image",
+    TextToVideo = "text-to-video",
+    ImageToVideo = "image-to-video",
+    VideoToVideo = "video-to-video",
+    TextToSpeech = "text-to-speech",
+    TextToAudio = "text-to-audio",
+    SpeechToText = "speech-to-text",
+    ImageToAudio = "image-to-audio",
+    AudioToAudio = "audio-to-audio",
+    SpeechToSpeech = "speech-to-speech",
+    ChatCompletions = "chat-completions",
+    AudioToVideo = "audio-to-video",
+    VideoToAudio = "video-to-audio"
+}
+export declare enum PricingUnit {
+    Generation = "generation",
+    Megapixel = "megapixel",
+    Second = "second",
+    ThirtySecond = "30_second",
+    Minute = "minute",
+    ThousandCharacters = "1k_characters",
+    InputTokens = "input_tokens",
+    InputTextTokens = "input_text_tokens",
+    InputCachedTokens = "input_cached_tokens",
+    OutputImageTokens = "output_image_tokens",
+    OutputAudioTokens = "output_audio_tokens",
+    OutputTextTokens = "output_text_tokens"
+}
+export interface ModelPricingFilters {
+    vendor?: string;
+    modelId?: string;
+    useCase?: UseCase;
+    quality?: string;
+    audio?: boolean;
+}
+export interface ModelPricingMetadata {
+    vendor: string;
+    model: string;
+    modelId: string;
+    useCase: UseCase;
+    quality: string;
+    audio: boolean;
+}
+export interface SkuEntry {
+    id: string;
+}
+export interface VendorCostEntry {
+    cost: number;
+    unit: PricingUnit;
+    skus: SkuEntry[];
+}
+export interface ModelPricing {
+    id: string;
+    operationId: string;
+    metadata: ModelPricingMetadata;
+    vendorCosts: VendorCostEntry[];
+    unit: PricingUnit;
+    credits: number;
+    costPerUnit: number;
+    legacy: boolean;
+    created: string;
+    updated: string;
+}
+export interface ModelPricingListResponse {
+    status: string;
+    response: ModelPricing[];
+}
+export interface ModelPricingClientOptions {
+    /** Base URL of the model pricing service. */
+    baseUrl: string;
+    /**
+     * Custom fetch implementation.
+     * When provided, the client delegates all HTTP calls to this function.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Extra headers to include in every request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Interval in milliseconds at which the in-memory cache is refreshed by the
+     * background scheduler. The cache itself never expires; it is only replaced
+     * by a successful refresh. Set 0 to disable the scheduler.
+     * @default 600_000 (10 minutes)
+     */
+    refreshIntervalMs?: number;
+    /**
+     * HTTP request timeout in milliseconds.
+     * @default 5_000
+     */
+    timeoutMs?: number;
+}

package/_vendor/workflows-client/index.d.ts

@@ -0,0 +1,131 @@
+import { WorkflowTypes } from '../workflows-types/index';
+export { WorkflowTypes } from '../workflows-types/index';
+
+declare enum PicsartStatus {
+    SUCCESS = "success",
+    ERROR = "error"
+}
+type PicsartResponse = {
+    status: PicsartStatus.SUCCESS;
+};
+declare enum WorkflowStatus {
+    ACCEPTED = "ACCEPTED",
+    FAILED = "FAILED",
+    COMPLETED = "COMPLETED",
+    IN_PROGRESS = "IN_PROGRESS"
+}
+interface TaskCreditUsage {
+    toolId: string;
+    price: number;
+    amount: number;
+    credits: number;
+    details?: ToolUsage[];
+}
+interface ToolUsage {
+    toolId: string;
+    price: number;
+    amount: number;
+    credits: number;
+}
+type WorkflowApiResponse<R> = {
+    id: string;
+    status: WorkflowStatus;
+    updated: string;
+    result: R;
+    progress?: WorkflowProgress;
+    usage?: TaskCreditUsage;
+    events?: WorkflowEvent[];
+};
+type PartialWorkflowResult<R> = {
+    status: WorkflowStatus;
+    result: R;
+};
+type HistoryResponse<R> = PicsartResponse & {
+    response: {
+        id: string;
+        created: string;
+        status: WorkflowStatus;
+        params: {
+            prompt: string;
+        };
+        result: (R | null)[];
+    }[];
+};
+type WorkflowProgress = {
+    percent: number;
+    estimatedSecondsLeft?: number;
+};
+type OnPartialResultFn = <R>(result: WorkflowApiResponse<R> | PartialWorkflowResult<R>) => Promise<void> | void;
+type OnProgressFn = (progress: WorkflowProgress) => Promise<void> | void;
+declare enum ExecutionMode {
+    ASYNC = "ASYNC",
+    SYNC = "SYNC",
+    STREAM = "STREAM"
+}
+declare class ExecutionOptions {
+    mode?: ExecutionMode;
+    remoteSettingName?: string;
+    abortSignal?: AbortSignal;
+    retriesCount?: number;
+    pollingInterval?: number;
+    onPartialResult?: OnPartialResultFn;
+    onProgress?: OnProgressFn;
+    onAccepted?: (id: string) => Promise<void> | void;
+    onEvent?: (event: WorkflowEvent) => Promise<void> | void;
+    notificationConfig?: INotificationContext;
+    headers?: HeadersInit;
+}
+declare class ApiSettings {
+    executionMode?: ExecutionMode;
+    configId?: string;
+}
+interface WorkflowEvent {
+    type: string;
+    id?: string;
+}
+interface WorkflowResponse<R> {
+    result: R;
+    usage?: TaskCreditUsage;
+}
+interface INotificationContext {
+    projectId?: string;
+    miniappPackageId?: string;
+    actions?: INotificationContextAction[];
+}
+interface INotificationContextAction {
+    deeplink: string;
+    mobileDeeplink: string;
+}
+
+type getRemoteSettingsFn = (name: string, tag?: string) => Promise<ApiSettings>;
+interface ClientOptions {
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    apiKey?: string;
+    identityToken?: string;
+    getRemoteSettings?: getRemoteSettingsFn;
+    headers?: HeadersInit;
+}
+declare class WorkflowsClient {
+    private readonly workflowsApiBaseUrl;
+    private readonly defaultHeaders;
+    private readonly options;
+    private readonly terminalStatuses;
+    constructor(options: ClientOptions);
+    run<R>(name: string, params: unknown, executionOptions?: ExecutionOptions): Promise<WorkflowResponse<R>>;
+    runTypeSafe<N extends keyof WorkflowTypes>(name: N, params: WorkflowTypes[N]['params'], executionOptions?: ExecutionOptions): Promise<WorkflowResponse<WorkflowTypes[N]['result']>>;
+    private postTask;
+    runPolling<R>(taskName: string, taskId: string, executionOptions?: ExecutionOptions): Promise<WorkflowResponse<R>>;
+    private executeTaskSync;
+    private getResult;
+    private executeTaskStream;
+    executionsHistory<R>(taskName: string, offset?: number, limit?: number, isGrouped?: boolean): Promise<HistoryResponse<R>>;
+    private toSuccessResponse;
+    private throwIfError;
+    private getApiSettings;
+    private wrapError;
+    private buildRequestHeaders;
+    private _fetch;
+}
+
+export { ExecutionMode, ExecutionOptions, type WorkflowEvent, type WorkflowProgress, type WorkflowResponse, WorkflowStatus, WorkflowsClient };