@picsart/ai-sdk 6.13.1 → 6.13.3

package/index.d.ts

@@ -343,6 +343,7 @@ type ModelInputById = {
         prompt: string;
         aspectRatio?: "1:1" | "16:9" | "9:16" | "3:4" | "4:3" | "2:3" | "21:9" | "auto";
         count?: 1 | 2 | 4 | 6 | 8 | 10;
+        seed?: number;
         imageUrls?: string[];
     };
     "gemini-2.5-flash-tts": {
@@ -368,6 +369,7 @@ type ModelInputById = {
         aspectRatio?: "1:1" | "16:9" | "9:16" | "3:4" | "4:3" | "2:3" | "21:9" | "auto";
         resolution?: "1K" | "2K" | "4K";
         count?: 1 | 2 | 4 | 6 | 8 | 10;
+        seed?: number;
         thinkingBudget?: number;
         imageUrls?: string[];
     };
@@ -376,6 +378,7 @@ type ModelInputById = {
         aspectRatio?: "1:1" | "16:9" | "9:16" | "3:4" | "4:3" | "3:2" | "2:3" | "4:5" | "5:4" | "4:1" | "1:4" | "8:1" | "1:8" | "21:9" | "auto";
         resolution?: "0.5K" | "1K" | "2K" | "4K";
         count?: 1 | 2 | 4 | 6 | 8 | 10;
+        seed?: number;
         thinkingLevel?: "minimal" | "high";
         imageUrls?: string[];
     };
@@ -383,6 +386,7 @@ type ModelInputById = {
         prompt: string;
         aspectRatio?: "1:1" | "16:9" | "9:16" | "3:4" | "4:3" | "3:2" | "2:3" | "4:5" | "5:4" | "4:1" | "1:4" | "8:1" | "1:8" | "21:9" | "auto";
         count?: 1 | 2 | 4 | 6 | 8 | 10;
+        seed?: number;
         thinkingLevel?: "minimal" | "high";
         imageUrls?: string[];
     };
@@ -1922,219 +1926,71 @@ type ModelInput<M extends TypedModelId> = ModelInputById[M];
 type TextModelId = "claude-fable-5" | "claude-fable-5-1" | "claude-haiku-4-5" | "claude-opus-4-8" | "claude-opus-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-5" | "eleven-speech-to-text" | "gemini-2.5-flash" | "gemini-3-pro" | "gemini-3.5-flash-lite" | "gemini-3.6-flash" | "gemini-3.7-flash" | "gemini-3.8-flash" | "gpt-4.1-mini" | "gpt-4.1-nano" | "gpt-4o" | "gpt-4o-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5.1" | "gpt-5.2" | "gpt-5.5" | "gpt-5.6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-6-astra";
 type TextModelInputById = Pick<ModelInputById, TextModelId>;
 
-/**
- * Per-item vendor metadata promoted from the response. Every key is
- * best-effort: present when the vendor reports it, absent otherwise.
- */
-interface GenerateResultItemMetadata {
-    /** Explore image id (recraft explore models) — pass back as `sourceImageId`
-     *  to iterate on this image. */
-    exploreImageId?: string;
-    /** Voice preview id (ElevenLabs voice design/remix) — pass to the vendor's
-     *  create-voice-from-preview step to persist the voice. */
-    generatedVoiceId?: string;
-    /** URL of the generated video's last frame, when the model was asked for it
-     *  (`returnLastFrame`, seedance) — the seed for frame-chaining flows. */
-    lastFrameUrl?: string;
-    /** The draft a Seedance 2.5 Draft generation produced — pass it back
-     *  unchanged as `draftTask` to the matching `-draft-final` model to render
-     *  the final 1080p video (valid 7 days). Wire field names on purpose: the
-     *  worker signs it, so any change is rejected. */
-    draftTask?: SeedanceDraftTask;
-}
-/** A Seedance 2.5 draft reference, as the worker issues it. */
-interface SeedanceDraftTask {
-    id: string;
-    video_input: boolean;
-    signature: string;
+interface ParamSchema {
+    type: 'string' | 'number' | 'boolean' | 'file';
+    enum?: (string | number)[];
+    default?: string | number | boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    required?: boolean;
+    label?: string;
+    accept?: string;
 }
+type ModelParamSchema = Record<string, ParamSchema>;
 
 /**
- * Drive client — manages folders and file saving in Picsart Drive.
+ * Runtime catalogs — the standard format served by the platform
+ * `<vendor>/v1/catalog/<voices|avatars|…>` tasks (voices, avatars, effect
+ * templates), plus the in-memory hydration registry that lets runtime-fetched
+ * catalogs back the descriptor system.
  *
- * Uses the same authenticated fetch as the generation client.
- * Root folder is auto-created on first use and cached.
+ * The wire types mirror the shared backend contract (`@picsart/pa-genai-common`);
+ * the SDK owns its own copy so it carries no backend dependency.
  */
 
-type MediaTypeFilter = 'image' | 'video' | 'audio';
-type UserReaction = 'like' | 'dislike';
-/** A folder reference in Picsart Drive. */
-interface DriveFolder {
-    name: string;
-    uid: string;
-}
-/** Drive save result, attached to GenerateResult when drive is enabled. */
-interface DriveSaveResult {
-    uid: string;
-    folder: DriveFolder;
-}
-/**
- * The generation input parameters, serialized into the `aiSDKPayload` attribute.
- * Captures every value from the generation context — the named fields below are
- * common ones for convenience; the index signature carries any other input param.
- */
-interface SdkPayload {
-    prompt: string;
-    aspectRatio?: string;
-    duration?: number;
-    resolution?: string;
-    generateAudio?: boolean;
-    imageUrls?: string[];
-    videoUrls?: string[];
-    audioUrls?: string[];
-    startFrame?: string;
-    endFrame?: string;
+interface CatalogPreview {
+    imageUrl?: string;
     videoUrl?: string;
     audioUrl?: string;
-    [key: string]: unknown;
-}
-type DriveFile = {
-    uid: string;
-} & Record<string, unknown>;
-interface DriveAttributes {
-    model: string;
-    /** JSON-encoded SdkPayload (all generation input params). */
-    aiSDKPayload: string;
-    appId?: string;
-    appType?: AppType;
-}
-/** A saved Seedance 2.5 draft — pass `draftTask` unchanged as the final's
- *  `draftTask` param until `draftExpiresAt`. */
-interface DriveDraftInfo {
-    draftTask?: SeedanceDraftTask;
-    /** ISO timestamp after which the vendor no longer renders a final from it. */
-    draftExpiresAt?: string;
-}
-interface GenerationFile extends DriveDraftInfo {
-    appId?: string;
-    appType?: AppType;
-    model?: string;
-    aiSDKPayload?: SdkPayload;
-    userReaction?: UserReaction;
-}
-interface DriveMediaItem {
-    uid: string;
-    url: string;
-    name: string;
-    type: MediaTypeFilter;
-    previewUrl?: string;
-    timestamp: number;
-}
-interface DriveFileDetails extends DriveMediaItem, DriveDraftInfo {
-    createdAt?: string;
-    model?: string;
-    prompt?: string;
-    service?: string;
-    subType?: string;
-    duration?: string;
-    aspectRatio?: string;
-    resolution?: string;
-    quality?: string;
-    userReaction?: UserReaction;
-    referenceImageUrls?: string[];
-    referenceVideoUrl?: string;
-    referenceAudioUrl?: string;
-}
-interface ListOptions {
-    folder?: DriveFolder;
-    type?: MediaTypeFilter;
-}
-interface SaveParams {
-    url: string;
-    name: string;
-    resourceType: 'PHOTO' | 'VIDEO' | 'AUDIO';
-    attributes?: Record<string, string>;
-    previewUrl?: string;
 }
-/** Target folder for backend Drive save. */
-interface PayloadDriveFolderOptions {
-    /** Folder path — backend resolves it (e.g. 'AI Playground' or 'AI Playground/My Board'). */
-    path?: string;
-    /** Folder UID — overrides path when provided. */
-    id?: string;
-}
-/** Drive save options injected into the workflow payload as `options.drive`. */
-interface PayloadDriveOptions {
-    /** Filename for the saved asset. */
+interface CatalogItem {
+    /** Vendor-native id, sent back verbatim on generate as the bound param's value. */
+    id: string;
     name: string;
-    /** Generation attributes attached to the file (SDK-assembled, fixed shape). */
-    attributes?: DriveAttributes;
-    /** Target folder in Picsart Drive. */
-    folder?: PayloadDriveFolderOptions;
+    description?: string;
+    /** Facets for filtering: gender, language, age, accent, tone, … */
+    tags: string[];
+    preview?: CatalogPreview;
+    /** Vendor extras, e.g. `defaultVoiceId` on HeyGen avatars. */
+    meta?: Record<string, unknown>;
 }
-/**
- * Drive operations surface — returned by {@link createDriveClient} and exposed
- * as `ai.drive` when Drive is configured. Manages folders, listing, saving, and
- * reactions in Picsart Drive.
- */
-interface DriveClient {
-    /** Ensure a folder exists (creating it if needed) and return it. */
-    ensureFolder(subfolder?: string): Promise<DriveFolder | null>;
-    /** List the immediate subfolders of the root folder. */
-    folders(): Promise<DriveFolder[]>;
-    /** List all folders recursively. */
-    allFolders(): Promise<DriveFolder[]>;
-    /** Find a folder by name. */
-    findFolder(name: string): Promise<DriveFolder | null>;
-    /** List media items in a folder. */
-    list(options?: ListOptions): Promise<DriveMediaItem[]>;
-    /** List media items in a folder with full generation metadata. */
-    listDetailed(options?: ListOptions): Promise<DriveFileDetails[]>;
-    /** Read a single generation's stored attributes. */
-    getGeneration(fileUid: string): Promise<GenerationFile | null>;
-    /** Save an asset to Drive. */
-    save(params: SaveParams, folder?: DriveFolder): Promise<DriveSaveResult | null>;
-    /** Build the save params for a generation result. */
-    buildSaveParams(url: string, modelId: string, modelName: string, mode: string, prompt?: string): SaveParams;
-    /** Set a like/dislike reaction on a file. */
-    addReaction(fileUid: string, reaction: UserReaction): Promise<boolean>;
-    /** Clear the reaction on a file. */
-    removeReaction(fileUid: string): Promise<boolean>;
+interface CatalogQuery {
+    /** Worker-side filter (e.g. the seed-audio model variant on bytedance). */
+    modelId?: string;
+    /** Opaque cursor from a previous page. */
+    cursor?: string;
+    /** Page size. Every catalog task accepts up to 100. */
+    limit?: number;
 }
-declare function inferResourceType(mode: string): 'PHOTO' | 'VIDEO' | 'AUDIO';
-declare function buildFilename(prompt: string | undefined, mode: string): string;
-declare function buildGenerationAttributes(input: {
-    modelId: string;
-    params: Record<string, unknown>;
-    /** TODO(backend-autosave): temporary — remove once the backend stamps appId/appType. */
-    app?: AppIdentity;
-}): DriveAttributes;
-declare function parseGeneration(file: DriveFile | Record<string, unknown>): GenerationFile;
-
-/** Result of `ai.apis.run()` — the API result plus optional credit usage. */
-type ApiResponse<R = unknown> = WorkflowResponse<R>;
-/**
- * Options for `ai.apis.run()` — execution mode, polling, abort signal, progress callbacks.
- * Intentionally omits the lib's `remoteSettingName` (a no-op without remote settings),
- * `onPartialResult`, and `notificationConfig` — these aren't part of the SDK surface.
- */
-type ApiRunOptions = Omit<ExecutionOptions, 'remoteSettingName' | 'onPartialResult' | 'notificationConfig'>;
-/** Registry of known API names → their params/result types (from @picsart/workflows-types). */
-type ApiSchemas = WorkflowTypes;
-/**
- * The `ai.apis` surface — direct, low-level access to the Picsart model APIs.
- * Known API names (keys of {@link ApiSchemas}) get typed params + result;
- * unknown names take an open payload and return an unknown result.
- *
- * Failures arrive as {@link ApiError}, the same as the generation surface.
- */
-interface ApisClient {
-    /** Run an API by name (mirrors WorkflowsClient.run()). */
-    run<W extends string = string>(api: W, payload: W extends keyof ApiSchemas ? ApiSchemas[W]['params'] : Record<string, unknown>, options?: ApiRunOptions): Promise<ApiResponse<W extends keyof ApiSchemas ? ApiSchemas[W]['result'] : unknown>>;
+interface CatalogResult {
+    items: CatalogItem[];
+    /** Crawl date or curation stamp identifying the snapshot. */
+    version: string;
+    /** How long the caller may cache this response. */
+    ttlSeconds: number;
+    /** `null` when the list is complete. */
+    nextCursor: string | null;
 }
-
-interface ParamSchema {
-    type: 'string' | 'number' | 'boolean' | 'file';
-    enum?: (string | number)[];
-    default?: string | number | boolean;
-    min?: number;
-    max?: number;
-    step?: number;
-    required?: boolean;
-    label?: string;
-    accept?: string;
+/** Binds a param's options to a platform catalog task. */
+interface CatalogSource {
+    /** Catalog workflow name, e.g. `heygen/v1/catalog/voices`. */
+    workflow: string;
+    /** Worker-side filter passed on fetch. */
+    modelId?: string;
 }
-type ModelParamSchema = Record<string, ParamSchema>;
+declare function toVoiceOption(item: CatalogItem, provider: Provider): VoiceOption;
+declare function toAvatarOption(item: CatalogItem, provider: Provider): AvatarOption;
 
 /**
  * Param Descriptor types — the new, open-ended parameter definition system.
@@ -2653,6 +2509,12 @@ interface ModelDefinition {
     /** I2V/edit payload builder when different from buildPayload. */
     buildEditPayload?: PayloadBuilder;
     outputSchema?: RuntimeSchema<unknown>;
+    /**
+     * File extension the model produces when it has no output-format param
+     * (e.g. 'jpg'). Used to name a Drive save made before the job runs; without
+     * it the mode default applies (png / mp4 / mp3).
+     */
+    outputExtension?: string;
     estimatedTime?: number | Record<string, number>;
     editEstimatedTime?: number | Record<string, number>;
     testTimeout?: number;
@@ -2669,57 +2531,227 @@ interface ModelDefinition {
 }
 
 /**
- * Runtime catalogs — the standard format served by the platform
- * `<vendor>/v1/catalog/<voices|avatars|…>` tasks (voices, avatars, effect
- * templates), plus the in-memory hydration registry that lets runtime-fetched
- * catalogs back the descriptor system.
+ * Per-item vendor metadata promoted from the response. Every key is
+ * best-effort: present when the vendor reports it, absent otherwise.
+ */
+interface GenerateResultItemMetadata {
+    /** Explore image id (recraft explore models) — pass back as `sourceImageId`
+     *  to iterate on this image. */
+    exploreImageId?: string;
+    /** Voice preview id (ElevenLabs voice design/remix) — pass to the vendor's
+     *  create-voice-from-preview step to persist the voice. */
+    generatedVoiceId?: string;
+    /** URL of the generated video's last frame, when the model was asked for it
+     *  (`returnLastFrame`, seedance) — the seed for frame-chaining flows. */
+    lastFrameUrl?: string;
+    /** The draft a Seedance 2.5 Draft generation produced — pass it back
+     *  unchanged as `draftTask` to the matching `-draft-final` model to render
+     *  the final 1080p video (valid 7 days). Wire field names on purpose: the
+     *  worker signs it, so any change is rejected. */
+    draftTask?: SeedanceDraftTask;
+}
+/** A Seedance 2.5 draft reference, as the worker issues it. */
+interface SeedanceDraftTask {
+    id: string;
+    video_input: boolean;
+    signature: string;
+}
+
+/**
+ * Drive client — manages folders and file saving in Picsart Drive.
  *
- * The wire types mirror the shared backend contract (`@picsart/pa-genai-common`);
- * the SDK owns its own copy so it carries no backend dependency.
+ * Uses the same authenticated fetch as the generation client.
+ * Root folder is auto-created on first use and cached.
  */
 
-interface CatalogPreview {
-    imageUrl?: string;
+type MediaTypeFilter = 'image' | 'video' | 'audio';
+type UserReaction = 'like' | 'dislike';
+/** A folder reference in Picsart Drive. */
+interface DriveFolder {
+    name: string;
+    uid: string;
+}
+/** Drive save result, attached to GenerateResult when drive is enabled. */
+interface DriveSaveResult {
+    uid: string;
+    folder: DriveFolder;
+}
+/**
+ * The generation input parameters, serialized into the `aiSDKPayload` attribute.
+ * Captures every value from the generation context — the named fields below are
+ * common ones for convenience; the index signature carries any other input param.
+ */
+interface SdkPayload {
+    prompt: string;
+    aspectRatio?: string;
+    duration?: number;
+    resolution?: string;
+    generateAudio?: boolean;
+    imageUrls?: string[];
+    videoUrls?: string[];
+    audioUrls?: string[];
+    startFrame?: string;
+    endFrame?: string;
     videoUrl?: string;
     audioUrl?: string;
+    [key: string]: unknown;
 }
-interface CatalogItem {
-    /** Vendor-native id, sent back verbatim on generate as the bound param's value. */
-    id: string;
+type DriveFile = {
+    uid: string;
+} & Record<string, unknown>;
+interface DriveAttributes {
+    model: string;
+    /** JSON-encoded SdkPayload (all generation input params). */
+    aiSDKPayload: string;
+    appId?: string;
+    appType?: AppType;
+}
+/** A saved Seedance 2.5 draft — pass `draftTask` unchanged as the final's
+ *  `draftTask` param until `draftExpiresAt`. */
+interface DriveDraftInfo {
+    draftTask?: SeedanceDraftTask;
+    /** ISO timestamp after which the vendor no longer renders a final from it. */
+    draftExpiresAt?: string;
+}
+interface GenerationFile extends DriveDraftInfo {
+    appId?: string;
+    appType?: AppType;
+    model?: string;
+    aiSDKPayload?: SdkPayload;
+    userReaction?: UserReaction;
+}
+interface DriveMediaItem {
+    uid: string;
+    url: string;
     name: string;
-    description?: string;
-    /** Facets for filtering: gender, language, age, accent, tone, … */
-    tags: string[];
-    preview?: CatalogPreview;
-    /** Vendor extras, e.g. `defaultVoiceId` on HeyGen avatars. */
-    meta?: Record<string, unknown>;
+    type: MediaTypeFilter;
+    previewUrl?: string;
+    timestamp: number;
 }
-interface CatalogQuery {
-    /** Worker-side filter (e.g. the seed-audio model variant on bytedance). */
-    modelId?: string;
-    /** Opaque cursor from a previous page. */
-    cursor?: string;
-    /** Page size. Every catalog task accepts up to 100. */
-    limit?: number;
+interface DriveFileDetails extends DriveMediaItem, DriveDraftInfo {
+    createdAt?: string;
+    model?: string;
+    prompt?: string;
+    service?: string;
+    subType?: string;
+    duration?: string;
+    aspectRatio?: string;
+    resolution?: string;
+    quality?: string;
+    userReaction?: UserReaction;
+    referenceImageUrls?: string[];
+    referenceVideoUrl?: string;
+    referenceAudioUrl?: string;
 }
-interface CatalogResult {
-    items: CatalogItem[];
-    /** Crawl date or curation stamp identifying the snapshot. */
-    version: string;
-    /** How long the caller may cache this response. */
-    ttlSeconds: number;
-    /** `null` when the list is complete. */
-    nextCursor: string | null;
+interface ListOptions {
+    folder?: DriveFolder;
+    type?: MediaTypeFilter;
 }
-/** Binds a param's options to a platform catalog task. */
-interface CatalogSource {
-    /** Catalog workflow name, e.g. `heygen/v1/catalog/voices`. */
-    workflow: string;
-    /** Worker-side filter passed on fetch. */
-    modelId?: string;
+interface SaveParams {
+    url: string;
+    name: string;
+    resourceType: 'PHOTO' | 'VIDEO' | 'AUDIO';
+    attributes?: Record<string, string>;
+    previewUrl?: string;
+}
+/** Target folder for backend Drive save. */
+interface PayloadDriveFolderOptions {
+    /** Folder path — backend resolves it (e.g. 'AI Playground' or 'AI Playground/My Board'). */
+    path?: string;
+    /** Folder UID — overrides path when provided. */
+    id?: string;
+}
+/** Drive save options injected into the workflow payload as `options.drive`. */
+interface PayloadDriveOptions {
+    /** Filename for the saved asset. */
+    name: string;
+    /** Generation attributes attached to the file (SDK-assembled, fixed shape). */
+    attributes?: DriveAttributes;
+    /** Target folder in Picsart Drive. */
+    folder?: PayloadDriveFolderOptions;
+}
+/**
+ * Drive operations surface — returned by {@link createDriveClient} and exposed
+ * as `ai.drive` when Drive is configured. Manages folders, listing, saving, and
+ * reactions in Picsart Drive.
+ */
+interface DriveClient {
+    /** Ensure a folder exists (creating it if needed) and return it. */
+    ensureFolder(subfolder?: string): Promise<DriveFolder | null>;
+    /** List the immediate subfolders of the root folder. */
+    folders(): Promise<DriveFolder[]>;
+    /** List all folders recursively. */
+    allFolders(): Promise<DriveFolder[]>;
+    /** Find a folder by name. */
+    findFolder(name: string): Promise<DriveFolder | null>;
+    /** List media items in a folder. */
+    list(options?: ListOptions): Promise<DriveMediaItem[]>;
+    /** List media items in a folder with full generation metadata. */
+    listDetailed(options?: ListOptions): Promise<DriveFileDetails[]>;
+    /** Read a single generation's stored attributes. */
+    getGeneration(fileUid: string): Promise<GenerationFile | null>;
+    /** Save an asset to Drive. */
+    save(params: SaveParams, folder?: DriveFolder): Promise<DriveSaveResult | null>;
+    /** Build the save params for a generation result. */
+    buildSaveParams(url: string, modelId: string, modelName: string, mode: string, prompt?: string): SaveParams;
+    /** Set a like/dislike reaction on a file. */
+    addReaction(fileUid: string, reaction: UserReaction): Promise<boolean>;
+    /** Clear the reaction on a file. */
+    removeReaction(fileUid: string): Promise<boolean>;
+}
+declare function inferResourceType(mode: string): 'PHOTO' | 'VIDEO' | 'AUDIO';
+/** What is known about the file being named. Every field is optional; the
+ *  most reliable one present wins (see `resolveExtension`). */
+interface FilenameHints {
+    /** MIME type of the produced file (e.g. `image/jpeg`). */
+    mimeType?: string;
+    /** URL of the produced file; its path extension is used when present. */
+    url?: string;
+    /** Output format requested of (or declared by) the model, e.g. `jpeg`, `mov`, `ogg_opus`. */
+    format?: string;
+}
+/**
+ * Pick a file extension for a generation. Most to least reliable: the result's
+ * MIME type, the result URL's path extension, the requested output format, then
+ * the mode default (png / mp4 / mp3).
+ */
+declare function resolveExtension(mode: string, hints?: FilenameHints): string;
+/**
+ * The output format a generation will produce, known before the job runs:
+ * an explicit format param, else that param's catalog default, else the
+ * model's declared `outputExtension`. Undefined when nothing is known.
+ */
+declare function expectedOutputFormat(model: Pick<ModelDefinition, 'paramConfig' | 'outputExtension'>, params: Record<string, unknown>): string | undefined;
+declare function buildFilename(prompt: string | undefined, mode: string, hints?: FilenameHints): string;
+declare function buildGenerationAttributes(input: {
+    modelId: string;
+    params: Record<string, unknown>;
+    /** TODO(backend-autosave): temporary — remove once the backend stamps appId/appType. */
+    app?: AppIdentity;
+}): DriveAttributes;
+declare function parseGeneration(file: DriveFile | Record<string, unknown>): GenerationFile;
+
+/** Result of `ai.apis.run()` — the API result plus optional credit usage. */
+type ApiResponse<R = unknown> = WorkflowResponse<R>;
+/**
+ * Options for `ai.apis.run()` — execution mode, polling, abort signal, progress callbacks.
+ * Intentionally omits the lib's `remoteSettingName` (a no-op without remote settings),
+ * `onPartialResult`, and `notificationConfig` — these aren't part of the SDK surface.
+ */
+type ApiRunOptions = Omit<ExecutionOptions, 'remoteSettingName' | 'onPartialResult' | 'notificationConfig'>;
+/** Registry of known API names → their params/result types (from @picsart/workflows-types). */
+type ApiSchemas = WorkflowTypes;
+/**
+ * The `ai.apis` surface — direct, low-level access to the Picsart model APIs.
+ * Known API names (keys of {@link ApiSchemas}) get typed params + result;
+ * unknown names take an open payload and return an unknown result.
+ *
+ * Failures arrive as {@link ApiError}, the same as the generation surface.
+ */
+interface ApisClient {
+    /** Run an API by name (mirrors WorkflowsClient.run()). */
+    run<W extends string = string>(api: W, payload: W extends keyof ApiSchemas ? ApiSchemas[W]['params'] : Record<string, unknown>, options?: ApiRunOptions): Promise<ApiResponse<W extends keyof ApiSchemas ? ApiSchemas[W]['result'] : unknown>>;
 }
-declare function toVoiceOption(item: CatalogItem, provider: Provider): VoiceOption;
-declare function toAvatarOption(item: CatalogItem, provider: Provider): AvatarOption;
 
 /**
  * ai.catalogs — runtime access to the platform catalog tasks
@@ -3489,4 +3521,4 @@ declare const getModel: (id: string) => ModelDefinition | undefined;
  */
 declare const findModel: (ref: string) => ModelDefinition | undefined;
 
-export { ALL_MODELS, type AiClient, ApiError, type ApiErrorCode, type ApiErrorInit, type ApiResponse, type ApiRunOptions, type ApiSchemas, type ApisClient, type AppIdentity, type AppType, type AuthenticatedFetch, type AvatarOption, type BooleanDescriptor, type BooleanEntry, type CatalogDescriptor, type CatalogEntry, type CatalogItem, type CatalogPage, type CatalogPageOptions, type CatalogPreview, type CatalogQuery, type CatalogResult, type CatalogSource, type CatalogsClient, type CatalogsOptions, type ClientConfig, type CreditRange, type CreditRangeContext, type CreditTier, type CreditUsage, DEFAULT_VISIBLE_RELEASES, type DeepLinkResult, type DriveAttributes, type DriveClient, type DriveConfig, type DriveDraftInfo, type DriveFile, type DriveFileDetails, type DriveFolder, type DriveMediaItem, type DriveSaveResult, type EntryMeta, type EnumDescriptor, type EnumEntry, type EnumOption, type FileDescriptor, type FileEntry, type FlatParamEntry, type GenerateOptions, type GenerateResult, type GenerateResultItem, type GenerateResultItemMetadata, type GenerateTextResult, type GenerationContext, type GenerationEvent, GenerationEventType, type GenerationFile, type GenerationMode, type GenerationOptions, type GenerationProgress, type ListOptions, type MediaModelId, type MediaTypeFilter, Model, type ModelDefinition, type ModelDescriptor, type ModelFilter, type ModelInput, type ModelInputById, type ModelMeta, type ModelParams, type ModelParamsAccessor, Models, type ObjectDescriptor, type ObjectEntry, type ParamDescriptor, type ParamEntry, type ParamOption, type PayloadDriveFolderOptions, type PayloadDriveOptions, type PayloadInputsTransformationOptions, type PricingOptions, type ProviderInfo, type RangeDescriptor, type RangeEntry, type ReleaseTag, type SaveParams, type SdkPayload, type SdkTransport, type SeedanceDraftTask, type TextDescriptor, type TextEntry, type TextModelId, type TextModelInputById, type ToolUsage, type TransportPollOptions, type TransportResult, type TypedModelId, type UserReaction, type ValidationResult, type VoiceOption, type WorkflowJobHandle, type WorkflowSubmitRequest, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, isVisibleForReleases, parseGeneration, releaseOf, toAvatarOption, toVoiceOption };
+export { ALL_MODELS, type AiClient, ApiError, type ApiErrorCode, type ApiErrorInit, type ApiResponse, type ApiRunOptions, type ApiSchemas, type ApisClient, type AppIdentity, type AppType, type AuthenticatedFetch, type AvatarOption, type BooleanDescriptor, type BooleanEntry, type CatalogDescriptor, type CatalogEntry, type CatalogItem, type CatalogPage, type CatalogPageOptions, type CatalogPreview, type CatalogQuery, type CatalogResult, type CatalogSource, type CatalogsClient, type CatalogsOptions, type ClientConfig, type CreditRange, type CreditRangeContext, type CreditTier, type CreditUsage, DEFAULT_VISIBLE_RELEASES, type DeepLinkResult, type DriveAttributes, type DriveClient, type DriveConfig, type DriveDraftInfo, type DriveFile, type DriveFileDetails, type DriveFolder, type DriveMediaItem, type DriveSaveResult, type EntryMeta, type EnumDescriptor, type EnumEntry, type EnumOption, type FileDescriptor, type FileEntry, type FlatParamEntry, type GenerateOptions, type GenerateResult, type GenerateResultItem, type GenerateResultItemMetadata, type GenerateTextResult, type GenerationContext, type GenerationEvent, GenerationEventType, type GenerationFile, type GenerationMode, type GenerationOptions, type GenerationProgress, type ListOptions, type MediaModelId, type MediaTypeFilter, Model, type ModelDefinition, type ModelDescriptor, type ModelFilter, type ModelInput, type ModelInputById, type ModelMeta, type ModelParams, type ModelParamsAccessor, Models, type ObjectDescriptor, type ObjectEntry, type ParamDescriptor, type ParamEntry, type ParamOption, type PayloadDriveFolderOptions, type PayloadDriveOptions, type PayloadInputsTransformationOptions, type PricingOptions, type ProviderInfo, type RangeDescriptor, type RangeEntry, type ReleaseTag, type SaveParams, type SdkPayload, type SdkTransport, type SeedanceDraftTask, type TextDescriptor, type TextEntry, type TextModelId, type TextModelInputById, type ToolUsage, type TransportPollOptions, type TransportResult, type TypedModelId, type UserReaction, type ValidationResult, type VoiceOption, type WorkflowJobHandle, type WorkflowSubmitRequest, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, expectedOutputFormat, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, isVisibleForReleases, parseGeneration, releaseOf, resolveExtension, toAvatarOption, toVoiceOption };

package/index.js

@@ -1119,6 +1119,7 @@ function defineModels(provider, configs) {
     if (c.editEstimatedTime !== void 0) model.editEstimatedTime = c.editEstimatedTime;
     if (c.testTimeout !== void 0) model.testTimeout = c.testTimeout;
     if (c.pollOptions !== void 0) model.pollOptions = c.pollOptions;
+    if (c.outputExtension !== void 0) model.outputExtension = c.outputExtension;
     if (c.badge !== void 0) model.badge = c.badge;
     if (c.addedAt !== void 0) model.addedAt = c.addedAt;
     if (c.deprecated !== void 0) model.deprecated = c.deprecated;
@@ -6377,6 +6378,7 @@ var buildGemini3ProImagePayload = (ctx) => ({
   prompt: ctx.prompt,
   model: "gemini-3-pro-image-preview",
   count: ctx.count ?? 1,
+  ...ctx.seed != null ? { seed: ctx.seed } : {},
   ...ctx.imageUrls?.length ? { imageUrls: ctx.imageUrls } : {},
   aspectRatio: ctx.aspectRatio ?? "1:1",
   imageSize: ctx.resolution ?? "2K",
@@ -6386,6 +6388,7 @@ var buildGeminiFlashImagePayload = (ctx) => ({
   prompt: ctx.prompt,
   model: "gemini-2.5-flash-image",
   count: ctx.count ?? 1,
+  ...ctx.seed != null ? { seed: ctx.seed } : {},
   ...ctx.imageUrls?.length ? { imageUrls: ctx.imageUrls } : {},
   aspectRatio: ctx.aspectRatio ?? "16:9"
 });
@@ -6393,6 +6396,7 @@ var buildGemini31FlashImagePayload = (ctx) => ({
   prompt: ctx.prompt,
   model: "gemini-3.1-flash-image-preview",
   count: ctx.count ?? 1,
+  ...ctx.seed != null ? { seed: ctx.seed } : {},
   ...ctx.imageUrls?.length ? { imageUrls: ctx.imageUrls } : {},
   aspectRatio: ctx.aspectRatio ?? "1:1",
   imageSize: ctx.resolution ?? "1K",
@@ -6402,6 +6406,7 @@ var buildGemini31FlashLiteImagePayload = (ctx) => ({
   prompt: ctx.prompt,
   model: "gemini-3.1-flash-lite-image",
   count: ctx.count ?? 1,
+  ...ctx.seed != null ? { seed: ctx.seed } : {},
   ...ctx.imageUrls?.length ? { imageUrls: ctx.imageUrls } : {},
   aspectRatio: ctx.aspectRatio ?? "1:1",
   imageSize: ctx.resolution ?? "1K",
@@ -6465,6 +6470,7 @@ var { MODELS: MODELS22 } = defineModels("google", [
       ...params.aspectRatio(["1:1", "16:9", "9:16", "3:4", "4:3", "3:2", "2:3", "4:5", "5:4", "4:1", "1:4", "8:1", "1:8", "21:9", "auto"], "1:1"),
       ...params.resolution(["0.5K", "1K", "2K", "4K"], "1K"),
       ...params.count(),
+      ...params.seed(),
       ...thinkingLevelParam,
       ...params.imageInput(14, "Source Images")
     }
@@ -6487,6 +6493,7 @@ var { MODELS: MODELS22 } = defineModels("google", [
       ...params.prompt(),
       ...params.aspectRatio(["1:1", "16:9", "9:16", "3:4", "4:3", "3:2", "2:3", "4:5", "5:4", "4:1", "1:4", "8:1", "1:8", "21:9", "auto"], "1:1"),
       ...params.count(),
+      ...params.seed(),
       ...thinkingLevelParam,
       ...params.imageInput(14, "Source Images")
     }
@@ -6510,6 +6517,7 @@ var { MODELS: MODELS22 } = defineModels("google", [
       ...params.aspectRatio([...GEMINI_AR_WIDE], "1:1"),
       ...params.resolution(["1K", "2K", "4K"], "2K"),
       ...params.count(),
+      ...params.seed(),
       ...thinkingBudgetParam,
       ...params.imageInput(14, "Source Images")
     }
@@ -6532,6 +6540,7 @@ var { MODELS: MODELS22 } = defineModels("google", [
       ...params.prompt(),
       ...params.aspectRatio([...GEMINI_AR_WIDE], "16:9"),
       ...params.count(),
+      ...params.seed(),
       ...params.imageInput(14, "Source Images")
     }
   },
@@ -8851,6 +8860,8 @@ var { MODELS: MODELS30 } = defineModels("picsart", [
     workflow: "pcp/v1/sana-sprint",
     syncExecute: true,
     buildPayload: buildPcpSanaSprintPayload,
+    // The worker returns JPEG and exposes no format param.
+    outputExtension: "jpg",
     estimatedTime: 3,
     mode: "image",
     inputType: "t2i",
@@ -11732,9 +11743,90 @@ function inferResourceType(mode) {
   if (mode === "audio") return "AUDIO";
   return "PHOTO";
 }
-function buildFilename(prompt, mode) {
+var MIME_EXTENSIONS = {
+  "image/jpeg": "jpg",
+  "image/jpg": "jpg",
+  "image/pjpeg": "jpg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "image/avif": "avif",
+  "image/heic": "heic",
+  "image/heif": "heif",
+  "image/bmp": "bmp",
+  "image/tiff": "tiff",
+  "image/svg+xml": "svg",
+  "video/mp4": "mp4",
+  "video/quicktime": "mov",
+  "video/webm": "webm",
+  "video/x-matroska": "mkv",
+  "video/x-msvideo": "avi",
+  "video/x-m4v": "m4v",
+  "audio/mpeg": "mp3",
+  "audio/mp3": "mp3",
+  "audio/wav": "wav",
+  "audio/x-wav": "wav",
+  "audio/wave": "wav",
+  "audio/vnd.wave": "wav",
+  "audio/ogg": "ogg",
+  "audio/opus": "ogg",
+  "audio/aac": "aac",
+  "audio/flac": "flac",
+  "audio/x-flac": "flac",
+  "audio/mp4": "m4a",
+  "audio/x-m4a": "m4a",
+  "audio/webm": "webm"
+};
+var EXTENSION_ALIASES = {
+  jpeg: "jpg",
+  jpe: "jpg",
+  tif: "tiff",
+  mpeg4: "mp4",
+  quicktime: "mov"
+};
+function normalizeExtension(raw) {
+  if (!raw) return void 0;
+  const ext = raw.trim().toLowerCase().replace(/^\./, "").split("_")[0];
+  if (!/^[a-z0-9]{2,5}$/.test(ext)) return void 0;
+  return EXTENSION_ALIASES[ext] ?? ext;
+}
+function extensionFromMime(mimeType) {
+  if (!mimeType) return void 0;
+  const base2 = mimeType.split(";")[0].trim().toLowerCase();
+  return MIME_EXTENSIONS[base2];
+}
+function extensionFromUrl(url) {
+  if (!url) return void 0;
+  let path;
+  try {
+    path = new URL(url).pathname;
+  } catch {
+    path = url.split(/[?#]/)[0];
+  }
+  const match = /\.([A-Za-z0-9]{2,5})$/.exec(path.split("/").pop() ?? "");
+  return normalizeExtension(match?.[1]);
+}
+function defaultExtension(mode) {
+  return mode === "video" ? "mp4" : mode === "audio" ? "mp3" : "png";
+}
+function resolveExtension(mode, hints = {}) {
+  return extensionFromMime(hints.mimeType) ?? extensionFromUrl(hints.url) ?? normalizeExtension(hints.format) ?? defaultExtension(mode);
+}
+var FORMAT_PARAM_KEYS = ["outputFormat", "output_format", "format"];
+function expectedOutputFormat(model, params2) {
+  for (const key of FORMAT_PARAM_KEYS) {
+    const value = params2[key];
+    if (typeof value === "string" && value) return value;
+  }
+  for (const key of FORMAT_PARAM_KEYS) {
+    const fallback = model.paramConfig?.[key]?.descriptor?.default;
+    if (typeof fallback === "string" && fallback) return fallback;
+  }
+  return model.outputExtension;
+}
+function buildFilename(prompt, mode, hints) {
   const shortId = String(Date.now()).slice(-6);
-  const ext = mode === "video" ? "mp4" : mode === "audio" ? "mp3" : "png";
+  const ext = resolveExtension(mode, hints);
   if (!prompt) return `ai-generation-${shortId}.${ext}`;
   const slug = prompt.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 50);
   return `${slug}-${shortId}.${ext}`;
@@ -12181,7 +12273,7 @@ function createDriveClient(f, apiUrl, rootFolderName) {
     buildSaveParams(url, modelId, modelName, mode, prompt) {
       return {
         url,
-        name: buildFilename(prompt, mode),
+        name: buildFilename(prompt, mode, { url }),
         resourceType: inferResourceType(mode),
         attributes: {
           tool: "ai-sdk",
@@ -12492,7 +12584,8 @@ function createClient(config) {
     });
     const folderPath = options?.folder?.name ?? driveConfig?.folder;
     return {
-      name: explicit?.name ?? buildFilename(params2.prompt, model.mode),
+      // Named before the job runs, so the requested/declared format is the best hint.
+      name: explicit?.name ?? buildFilename(params2.prompt, model.mode, { format: expectedOutputFormat(model, params2) }),
       // SDK-assembled attributes are the baseline; explicit attributes win per-key.
       attributes: { ...attributes, ...explicit?.attributes ?? {} },
       folder: explicit?.folder ?? (folderPath ? { path: folderPath } : void 0)
@@ -13817,4 +13910,4 @@ function decodeDeepLinkPayload(encoded) {
   return deserializePayload(encoded);
 }
 
-export { ALL_MODELS, ApiError, ExecutionMode as ApiRunMode, DEFAULT_VISIBLE_RELEASES, GenerationEventType, Model, Models, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, isVisibleForReleases, parseGeneration, releaseOf, toAvatarOption, toVoiceOption };
+export { ALL_MODELS, ApiError, ExecutionMode as ApiRunMode, DEFAULT_VISIBLE_RELEASES, GenerationEventType, Model, Models, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, expectedOutputFormat, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, isVisibleForReleases, parseGeneration, releaseOf, resolveExtension, toAvatarOption, toVoiceOption };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@picsart/ai-sdk",
-  "version": "6.13.1",
+  "version": "6.13.3",
   "type": "module",
   "description": "Type-safe SDK for 100+ AI models — image, video, audio, and text generation with Picsart",
   "license": "MIT",