@picsart/ai-sdk 3.17.5 → 3.18.0

package/README.md

@@ -1,17 +1,19 @@
 # @picsart/ai-sdk
 
-Generate images, videos, and audio with 100+ AI models.
+Generate images, video, audio, and text with 100+ AI models.
 
 ## Documentation
 
-Interactive guides deployed via GitLab Pages:
+Full guides, the model catalog, and the API reference live on the Picsart API Platform:
 
-- [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
+- [Documentation](https://picsart.com/api-platform/docs) -- overview and guides
+- [Quickstart](https://picsart.com/api-platform/docs/quickstart) -- install, authenticate, first generation
+- [SDK guide](https://picsart.com/api-platform/docs/sdk) -- client setup, `generate`/`generateText`, Drive, lifecycle
+- [Authentication](https://picsart.com/api-platform/docs/authentication) -- create an API key
+- [Model catalog](https://picsart.com/api-platform/models) -- browse every supported model
+- [API reference](https://picsart.com/api-platform/docs/api-reference)
 
-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)
+Repository: [github.com/PicsArt/ai-sdk](https://github.com/PicsArt/ai-sdk)
 
 ## Quick Start
 

package/index.d.ts

@@ -1798,6 +1798,8 @@ interface ModelMeta {
     readonly features: ModelFeature[];
     readonly badges: BadgeType[];
     readonly provider: ProviderInfo;
+    /** Release / availability tier (EAI-3). Absent on the definition ⇒ `'production'`. */
+    readonly release: ReleaseTag;
 }
 /** Parameter operations — fluent access to model params, schemas, defaults. */
 interface ModelParamsAccessor {
@@ -1870,6 +1872,14 @@ interface ModelDescriptor {
 interface ModelFilter$1 {
     output?: GenerationMode;
     provider?: string;
+    /**
+     * Release tiers to include. Omitted ⇒ the default visible set
+     * (`['production', 'general-availability']`). List the tiers you want
+     * explicitly to opt into `preview` — e.g. `['preview']` for stage-only
+     * models, or all three to include everything. `disabled`/`deprecated`
+     * models stay hidden regardless.
+     */
+    release?: ReleaseTag[];
 }
 
 type AppProvider = 'picsart' | 'google' | 'kling' | 'grok' | 'openai' | 'flux' | 'ideogram' | 'elevenlabs' | 'minimax' | 'wan' | 'seedance' | 'ltx' | 'seedream' | 'hunyuan' | 'pika' | 'runway' | 'luma' | 'ovi' | 'creatify' | 'veed' | 'bytedance' | 'qwen' | 'reve' | 'recraft' | 'videography' | 'topaz' | 'heygen' | 'happyhorse' | 'pixverse' | 'anthropic' | 'async';
@@ -2007,6 +2017,12 @@ interface Constraint {
     then: Record<string, Restriction>;
 }
 type BadgeType = 'new' | 'popular' | 'coming-soon' | 'fast' | 'premium' | 'hot';
+/**
+ * Model release / availability tier. See `ModelDefinition.release`.
+ * Ordered widest-exposure-last: `preview` (stage only) → `production` (our
+ * apps) → `general-availability` (enterprise / external use).
+ */
+type ReleaseTag = 'preview' | 'production' | 'general-availability';
 interface ModelDefinition {
     id: string;
     name: string;
@@ -2038,6 +2054,7 @@ interface ModelDefinition {
      * from default catalog lookups, same as `disabled`.
      */
     deprecated?: boolean;
+    release?: ReleaseTag;
     mode: GenerationMode;
     inputType: InputType;
     modelId?: string;
@@ -2321,9 +2338,13 @@ declare function isPricingLoaded(): boolean;
 
 /** Look up a single model descriptor by id. */
 type ModelFunction = (id: string) => ModelDescriptor;
-declare function _all(): ModelDescriptor[];
+declare function _all(filter?: {
+    release?: readonly ReleaseTag[];
+}): ModelDescriptor[];
 declare function _find(filter: ModelFilter$1): ModelDescriptor[];
-declare function _search(query: string): ModelDescriptor[];
+declare function _search(query: string, filter?: {
+    release?: readonly ReleaseTag[];
+}): ModelDescriptor[];
 /** Look up a single model descriptor: `Model('flux-2-pro').params()`. */
 declare const Model: ModelFunction;
 /**
@@ -2367,8 +2388,32 @@ declare function decodeDeepLinkPayload(encoded: string): DeepLinkResult | null;
 
 /** All models from all vendors. */
 declare const ALL_MODELS: ModelDefinition[];
+/**
+ * Models for a generation mode. By default returns only default-visible models
+ * (production / general-availability — preview, disabled and deprecated are
+ * hidden). `includeDisabled = true` returns every model of the mode, bypassing
+ * all gates. For release-tier filtering use `catalog.find({ output, release })`.
+ */
 declare const getModelsByMode: (mode: ModelDefinition["mode"], includeDisabled?: boolean) => ModelDefinition[];
 
+/**
+ * Release tags shown by default in discovery. `preview` is stage-only and
+ * opt-in (pass `release: ['preview', ...]`) — it is never in the default set.
+ */
+declare const DEFAULT_VISIBLE_RELEASES: readonly ReleaseTag[];
+/** Effective release tag of a model — absent ⇒ `'production'`. */
+declare const releaseOf: (m: ModelDefinition) => ReleaseTag;
+/**
+ * Whether `m` is visible for the requested `releases` (default: the production
+ * + general-availability set).
+ *
+ * `disabled` and `deprecated` are hard hides layered on top of `release`: a
+ * model carrying either is never visible, regardless of its release tag or the
+ * requested set. (`disabled` is being phased out in favour of
+ * `release: 'preview'` — EAI-3 — but is still honoured during the migration.)
+ */
+declare function isVisibleForReleases(m: ModelDefinition, releases?: readonly ReleaseTag[]): boolean;
+
 /** Look up a model by its ID or vendor modelId. */
 declare const getModel: (id: string) => ModelDefinition | undefined;
 /** Find a model by ID, workflow name, or display name (case-insensitive). */
@@ -2377,4 +2422,4 @@ declare const findModel: (ref: string) => ModelDefinition | undefined;
 /** Effect scenes that require two input images (e.g. hugs, kisses, swaps). */
 declare const KLING_DUAL_IMAGE_EFFECTS: ReadonlySet<string>;
 
-export { ALL_MODELS, type AiClient, type ApiResponse, type ApiRunOptions, type ApiSchemas, type ApisClient, type AppIdentity, type AppType, type AuthenticatedFetch, type AvatarOption, type BooleanDescriptor, type BooleanEntry, type ClientConfig, type CreditRange, type CreditRangeContext, type DeepLinkResult, type DriveAttributes, type DriveClient, type DriveConfig, 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 GenerateTextResult, type GenerationContext, type GenerationFile, type GenerationMode, KLING_DUAL_IMAGE_EFFECTS, type ListOptions, type MediaModelId, type MediaTypeFilter, Model, type ModelDefinition, type ModelDescriptor, type ModelFilter$1 as 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 PricingOptions, type ProviderInfo, type RangeDescriptor, type RangeEntry, type SaveParams, type SdkPayload, type SdkTransport, type TextDescriptor, type TextEntry, type TextModelId, type TextModelInputById, type TypedModelId, type UserReaction, type ValidationResult$1 as ValidationResult, type VoiceOption, type WorkflowJobHandle, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, parseGeneration };
+export { ALL_MODELS, type AiClient, type ApiResponse, type ApiRunOptions, type ApiSchemas, type ApisClient, type AppIdentity, type AppType, type AuthenticatedFetch, type AvatarOption, type BooleanDescriptor, type BooleanEntry, type ClientConfig, type CreditRange, type CreditRangeContext, DEFAULT_VISIBLE_RELEASES, type DeepLinkResult, type DriveAttributes, type DriveClient, type DriveConfig, 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 GenerateTextResult, type GenerationContext, type GenerationFile, type GenerationMode, KLING_DUAL_IMAGE_EFFECTS, type ListOptions, type MediaModelId, type MediaTypeFilter, Model, type ModelDefinition, type ModelDescriptor, type ModelFilter$1 as 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 PricingOptions, type ProviderInfo, type RangeDescriptor, type RangeEntry, type ReleaseTag, type SaveParams, type SdkPayload, type SdkTransport, type TextDescriptor, type TextEntry, type TextModelId, type TextModelInputById, type TypedModelId, type UserReaction, type ValidationResult$1 as ValidationResult, type VoiceOption, type WorkflowJobHandle, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, isVisibleForReleases, parseGeneration, releaseOf };

package/index.js

@@ -639,6 +639,14 @@ function transferValues(newParams, prev) {
   return ctx;
 }
 
+// src/core/visibility.ts
+var DEFAULT_VISIBLE_RELEASES = ["production", "general-availability"];
+var releaseOf = (m) => m.release ?? "production";
+function isVisibleForReleases(m, releases = DEFAULT_VISIBLE_RELEASES) {
+  if (m.disabled || m.deprecated) return false;
+  return releases.includes(releaseOf(m));
+}
+
 // src/core/providers.ts
 var providers = {
   picsart: { color: "#FF3399", label: "PA", name: "Picsart" },
@@ -1028,6 +1036,7 @@ function defineModels(provider, configs) {
     if (c.addedAt !== void 0) model.addedAt = c.addedAt;
     if (c.disabled !== void 0) model.disabled = c.disabled;
     if (c.deprecated !== void 0) model.deprecated = c.deprecated;
+    if (c.release !== void 0) model.release = c.release;
     if (c.modelId !== void 0) model.modelId = c.modelId;
     if (c.constraints !== void 0) model.constraints = c.constraints;
     const contract = createModelContract(model);
@@ -7826,7 +7835,7 @@ var ALL_MODELS = [
   ...MODELS35,
   ...MODELS36
 ];
-var getModelsByMode = (mode, includeDisabled = false) => ALL_MODELS.filter((m) => m.mode === mode && (includeDisabled || !m.disabled && !m.deprecated));
+var getModelsByMode = (mode, includeDisabled = false) => ALL_MODELS.filter((m) => m.mode === mode && (includeDisabled || isVisibleForReleases(m)));
 
 // src/core/contracts.ts
 function requireObject(value, message) {
@@ -9617,12 +9626,14 @@ var ModelMetaImpl = class {
   features;
   badges;
   provider;
+  release;
   constructor(def) {
     this.mode = def.mode;
     this.inputType = def.inputType;
     this.description = def.description;
     this.features = def.features;
     this.badges = def.badge ?? [];
+    this.release = def.release ?? "production";
     this.provider = {
       id: def.provider,
       name: def.providerName,
@@ -9678,21 +9689,24 @@ var ModelDescriptorImpl = class {
 function _model(id) {
   return new ModelDescriptorImpl(resolveModel(id));
 }
-function _all() {
-  return ALL_MODELS.filter((m) => !m.disabled && !m.deprecated).map((m) => new ModelDescriptorImpl(m));
+function _all(filter = {}) {
+  const releases = filter.release ?? DEFAULT_VISIBLE_RELEASES;
+  return ALL_MODELS.filter((m) => isVisibleForReleases(m, releases)).map((m) => new ModelDescriptorImpl(m));
 }
 function _find(filter) {
+  const releases = filter.release ?? DEFAULT_VISIBLE_RELEASES;
   return ALL_MODELS.filter((m) => {
-    if (m.disabled || m.deprecated) return false;
+    if (!isVisibleForReleases(m, releases)) return false;
     if (filter.output && m.mode !== filter.output) return false;
     if (filter.provider && m.provider !== filter.provider) return false;
     return true;
   }).map((m) => new ModelDescriptorImpl(m));
 }
-function _search(query) {
+function _search(query, filter = {}) {
+  const releases = filter.release ?? DEFAULT_VISIBLE_RELEASES;
   const q = query.toLowerCase();
   return ALL_MODELS.filter(
-    (m) => !m.disabled && !m.deprecated && (m.id.toLowerCase().includes(q) || m.name.toLowerCase().includes(q) || m.provider.toLowerCase().includes(q))
+    (m) => isVisibleForReleases(m, releases) && (m.id.toLowerCase().includes(q) || m.name.toLowerCase().includes(q) || m.provider.toLowerCase().includes(q))
   ).map((m) => new ModelDescriptorImpl(m));
 }
 var Model = _model;
@@ -10314,4 +10328,4 @@ function decodeDeepLinkPayload(encoded) {
   return deserializePayload(encoded);
 }
 
-export { ALL_MODELS, ExecutionMode as ApiRunMode, KLING_DUAL_IMAGE_EFFECTS, Model, Models, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, parseGeneration };
+export { ALL_MODELS, ExecutionMode as ApiRunMode, DEFAULT_VISIBLE_RELEASES, KLING_DUAL_IMAGE_EFFECTS, Model, Models, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, isVisibleForReleases, parseGeneration, releaseOf };

package/package.json

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