@picsart/ai-sdk 3.35.6 → 4.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +28 -0
- package/index.d.ts +292 -163
- package/index.js +263 -615
- package/package.json +1 -1
package/index.d.ts
CHANGED
|
@@ -58,7 +58,7 @@ type WorkflowSubscribeOptions = WorkflowPollOptions;
|
|
|
58
58
|
type ModelInputById = {
|
|
59
59
|
"async-flash-v1": {
|
|
60
60
|
prompt: string;
|
|
61
|
-
voiceId?:
|
|
61
|
+
voiceId?: string;
|
|
62
62
|
container?: "mp3" | "wav" | "raw";
|
|
63
63
|
sampleRate?: number;
|
|
64
64
|
encoding?: "pcm_s16le" | "pcm_f32le";
|
|
@@ -107,7 +107,7 @@ type ModelInputById = {
|
|
|
107
107
|
};
|
|
108
108
|
"eleven-multilingual-sts-v2": {
|
|
109
109
|
audioUrl: string;
|
|
110
|
-
voiceId?:
|
|
110
|
+
voiceId?: string;
|
|
111
111
|
language?: string;
|
|
112
112
|
accent?: string;
|
|
113
113
|
removeBackgroundNoise?: boolean;
|
|
@@ -116,18 +116,18 @@ type ModelInputById = {
|
|
|
116
116
|
language?: string;
|
|
117
117
|
accent?: string;
|
|
118
118
|
prompt: string;
|
|
119
|
-
voiceId?:
|
|
119
|
+
voiceId?: string;
|
|
120
120
|
};
|
|
121
121
|
"eleven-sts-v2": {
|
|
122
122
|
audioUrl: string;
|
|
123
|
-
voiceId?:
|
|
123
|
+
voiceId?: string;
|
|
124
124
|
removeBackgroundNoise?: boolean;
|
|
125
125
|
};
|
|
126
126
|
"eleven-v3": {
|
|
127
127
|
language?: string;
|
|
128
128
|
accent?: string;
|
|
129
129
|
prompt: string;
|
|
130
|
-
voiceId?:
|
|
130
|
+
voiceId?: string;
|
|
131
131
|
};
|
|
132
132
|
"eleven-voice-create": {
|
|
133
133
|
prompt: string;
|
|
@@ -139,7 +139,7 @@ type ModelInputById = {
|
|
|
139
139
|
prompt: string;
|
|
140
140
|
};
|
|
141
141
|
"eleven-voice-remix": {
|
|
142
|
-
voiceId?:
|
|
142
|
+
voiceId?: string;
|
|
143
143
|
prompt: string;
|
|
144
144
|
};
|
|
145
145
|
"elevenlabs-music-v2": {
|
|
@@ -202,13 +202,13 @@ type ModelInputById = {
|
|
|
202
202
|
language?: string;
|
|
203
203
|
accent?: string;
|
|
204
204
|
prompt: string;
|
|
205
|
-
voiceId?:
|
|
205
|
+
voiceId?: string;
|
|
206
206
|
};
|
|
207
207
|
"gemini-2.5-pro-tts": {
|
|
208
208
|
language?: string;
|
|
209
209
|
accent?: string;
|
|
210
210
|
prompt: string;
|
|
211
|
-
voiceId?:
|
|
211
|
+
voiceId?: string;
|
|
212
212
|
};
|
|
213
213
|
"gemini-3-pro": {
|
|
214
214
|
prompt: string;
|
|
@@ -327,7 +327,7 @@ type ModelInputById = {
|
|
|
327
327
|
language?: string;
|
|
328
328
|
accent?: string;
|
|
329
329
|
prompt: string;
|
|
330
|
-
voiceId?:
|
|
330
|
+
voiceId?: string;
|
|
331
331
|
};
|
|
332
332
|
"hailuo-03": {
|
|
333
333
|
prompt: string;
|
|
@@ -793,14 +793,6 @@ type ModelInputById = {
|
|
|
793
793
|
isInstrumental?: boolean;
|
|
794
794
|
outputFormat?: "url" | "hex";
|
|
795
795
|
};
|
|
796
|
-
"openai-tts-1": {
|
|
797
|
-
prompt: string;
|
|
798
|
-
voiceId?: "alloy" | "ash" | "ballad" | "coral" | "echo" | "fable" | "nova" | "onyx" | "sage" | "shimmer" | "verse";
|
|
799
|
-
};
|
|
800
|
-
"openai-tts-1-hd": {
|
|
801
|
-
prompt: string;
|
|
802
|
-
voiceId?: "alloy" | "ash" | "ballad" | "coral" | "echo" | "fable" | "nova" | "onyx" | "sage" | "shimmer" | "verse";
|
|
803
|
-
};
|
|
804
796
|
"ovi": {
|
|
805
797
|
prompt: string;
|
|
806
798
|
size?: "9:16" | "16:9" | "1:1" | "9:16+" | "16:9+" | "2:5" | "5:2";
|
|
@@ -1099,7 +1091,7 @@ type ModelInputById = {
|
|
|
1099
1091
|
};
|
|
1100
1092
|
"runway-avatar-video": {
|
|
1101
1093
|
style?: "game-character" | "music-superstar" | "game-character-man" | "cat-character" | "influencer" | "tennis-coach" | "human-resource" | "fashion-designer" | "cooking-teacher";
|
|
1102
|
-
voiceId?:
|
|
1094
|
+
voiceId?: string;
|
|
1103
1095
|
prompt?: string;
|
|
1104
1096
|
audioUrl?: string;
|
|
1105
1097
|
};
|
|
@@ -1127,7 +1119,7 @@ type ModelInputById = {
|
|
|
1127
1119
|
};
|
|
1128
1120
|
"seed-audio-1.0": {
|
|
1129
1121
|
prompt: string;
|
|
1130
|
-
voiceId?:
|
|
1122
|
+
voiceId?: string;
|
|
1131
1123
|
audioUrls?: string[];
|
|
1132
1124
|
imageUrls?: string[];
|
|
1133
1125
|
format?: "wav" | "mp3" | "pcm" | "ogg_opus";
|
|
@@ -1139,7 +1131,7 @@ type ModelInputById = {
|
|
|
1139
1131
|
};
|
|
1140
1132
|
"seed-audio-1.0-multilingual": {
|
|
1141
1133
|
prompt: string;
|
|
1142
|
-
voiceId?:
|
|
1134
|
+
voiceId?: string;
|
|
1143
1135
|
audioUrls?: string[];
|
|
1144
1136
|
imageUrls?: string[];
|
|
1145
1137
|
format?: "wav" | "mp3" | "pcm" | "ogg_opus";
|
|
@@ -1641,144 +1633,6 @@ interface ApisClient {
|
|
|
1641
1633
|
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>>;
|
|
1642
1634
|
}
|
|
1643
1635
|
|
|
1644
|
-
/** A fetch-like function that handles authentication (headers, cookies, etc.). */
|
|
1645
|
-
type AuthenticatedFetch = (url: string, init?: RequestInit) => Promise<Response>;
|
|
1646
|
-
/** Drive configuration — enables auto-saving generations to Picsart Drive. */
|
|
1647
|
-
interface DriveConfig {
|
|
1648
|
-
/** Root folder name in Drive. All generations save here. */
|
|
1649
|
-
folder: string;
|
|
1650
|
-
}
|
|
1651
|
-
/**
|
|
1652
|
-
* Whether the embedding app is a native client or a miniapp. Set backend-side
|
|
1653
|
-
* during save; surfaced read-only via `getGeneration`.
|
|
1654
|
-
*/
|
|
1655
|
-
type AppType = 'native' | 'miniapp';
|
|
1656
|
-
/**
|
|
1657
|
-
* App identity (appId + appType).
|
|
1658
|
-
* TODO(backend-autosave): temporary — the backend will stamp appId/appType on
|
|
1659
|
-
* save. Until then apps may pass this so it's persisted client-side.
|
|
1660
|
-
*/
|
|
1661
|
-
interface AppIdentity {
|
|
1662
|
-
id: string;
|
|
1663
|
-
type: AppType;
|
|
1664
|
-
}
|
|
1665
|
-
/**
|
|
1666
|
-
* Simple client config — pass the API base URL plus one auth source, and the
|
|
1667
|
-
* SDK handles the rest. The SDK knows the Picsart API endpoints and response
|
|
1668
|
-
* shapes internally.
|
|
1669
|
-
*
|
|
1670
|
-
* Provide exactly one of:
|
|
1671
|
-
* - `fetch` — your own authenticated fetch (you add headers/cookies), or
|
|
1672
|
-
* - `apiKey` — the SDK builds a fetch that sends `Authorization: Bearer <apiKey>`.
|
|
1673
|
-
*/
|
|
1674
|
-
interface ClientConfig {
|
|
1675
|
-
/**
|
|
1676
|
-
* Authenticated fetch function. The SDK calls this for all HTTP requests.
|
|
1677
|
-
* Provide this or `apiKey`. Takes precedence over `apiKey` when both are set.
|
|
1678
|
-
*/
|
|
1679
|
-
fetch?: AuthenticatedFetch;
|
|
1680
|
-
/**
|
|
1681
|
-
* Picsart API key. When `fetch` is not provided, the SDK builds an
|
|
1682
|
-
* authenticated fetch that sends `Authorization: Bearer <apiKey>` on every
|
|
1683
|
-
* request (a leading `Bearer ` is stripped if present).
|
|
1684
|
-
*/
|
|
1685
|
-
apiKey?: string;
|
|
1686
|
-
/** API base URL (e.g. 'https://api.picsart.com'). */
|
|
1687
|
-
apiUrl: string;
|
|
1688
|
-
/** Enable Drive integration — auto-save generations to a Drive folder. */
|
|
1689
|
-
drive?: DriveConfig;
|
|
1690
|
-
}
|
|
1691
|
-
interface GenerateResultItem {
|
|
1692
|
-
url: string;
|
|
1693
|
-
metadata?: Record<string, unknown>;
|
|
1694
|
-
}
|
|
1695
|
-
interface GenerateResult {
|
|
1696
|
-
/** Primary result URL (convenience shortcut for results[0].url). */
|
|
1697
|
-
url: string;
|
|
1698
|
-
/** All result items — single item for normal models, multiple for explore/multi-result models. */
|
|
1699
|
-
results: GenerateResultItem[];
|
|
1700
|
-
/** Model ID that produced this result. */
|
|
1701
|
-
model: string;
|
|
1702
|
-
/** Job handle for status tracking. */
|
|
1703
|
-
handle: WorkflowJobHandle;
|
|
1704
|
-
/** Raw parsed output for advanced consumers. */
|
|
1705
|
-
raw: unknown;
|
|
1706
|
-
/** Present when Drive is enabled and the file was saved. */
|
|
1707
|
-
drive?: DriveSaveResult;
|
|
1708
|
-
}
|
|
1709
|
-
/** Result of a text-generation (LLM) model. */
|
|
1710
|
-
interface GenerateTextResult {
|
|
1711
|
-
/** Generated text. */
|
|
1712
|
-
text: string;
|
|
1713
|
-
/** Model ID that produced this result. */
|
|
1714
|
-
model: string;
|
|
1715
|
-
/** Job handle for status tracking. */
|
|
1716
|
-
handle: WorkflowJobHandle;
|
|
1717
|
-
/** Raw parsed output — carries usage, finish reason, thinking trace, etc. */
|
|
1718
|
-
raw: unknown;
|
|
1719
|
-
}
|
|
1720
|
-
/** Options for individual generate() / submit() calls. */
|
|
1721
|
-
interface GenerateOptions {
|
|
1722
|
-
signal?: AbortSignal;
|
|
1723
|
-
/** Save to a specific subfolder instead of the root (legacy — used by SDK DriveConfig). */
|
|
1724
|
-
folder?: DriveFolder;
|
|
1725
|
-
/** Save result to Picsart Drive via backend. Injected into the workflow payload. */
|
|
1726
|
-
drive?: PayloadDriveOptions;
|
|
1727
|
-
/**
|
|
1728
|
-
* App identity stamped onto the saved generation (appId/appType).
|
|
1729
|
-
* TODO(backend-autosave): temporary — remove once the backend stamps these.
|
|
1730
|
-
*/
|
|
1731
|
-
app?: AppIdentity;
|
|
1732
|
-
}
|
|
1733
|
-
/** Non-text (image/video/audio) model IDs — the media generation surface. */
|
|
1734
|
-
type MediaModelId = Exclude<TypedModelId, TextModelId>;
|
|
1735
|
-
/** AI SDK client with type-safe, model-aware method signatures. */
|
|
1736
|
-
interface AiClient {
|
|
1737
|
-
/** Generate content using a media model. Text/LLM models use generateText(). */
|
|
1738
|
-
generate<M extends MediaModelId>(model: M, params: ModelInputById[M], options?: GenerateOptions): Promise<GenerateResult>;
|
|
1739
|
-
/** Generate text using an LLM model. Returns the generated text plus the raw response. */
|
|
1740
|
-
generateText<M extends TextModelId>(model: M, params: TextModelInputById[M], options?: GenerateOptions): Promise<GenerateTextResult>;
|
|
1741
|
-
/** Get exact credit cost for a model with specific parameters. */
|
|
1742
|
-
getCredits<M extends TypedModelId>(model: M, params: ModelInputById[M]): Promise<number | null>;
|
|
1743
|
-
/** Submit a generation job and get a handle back. Media models only. */
|
|
1744
|
-
submit<M extends MediaModelId>(model: M, params: ModelInputById[M], options?: GenerateOptions): Promise<WorkflowJobHandle>;
|
|
1745
|
-
/** Check the current status of a submitted job. */
|
|
1746
|
-
status(handle: WorkflowJobHandle, signal?: AbortSignal): Promise<WorkflowStatusResult<unknown>>;
|
|
1747
|
-
/** Poll a submitted job until it completes and return the parsed result. Media models only. */
|
|
1748
|
-
result(handle: WorkflowJobHandle, model: MediaModelId, options?: WorkflowPollOptions): Promise<GenerateResult>;
|
|
1749
|
-
/** Subscribe to live status updates for a submitted job. */
|
|
1750
|
-
subscribe(handle: WorkflowJobHandle, options?: WorkflowSubscribeOptions): AsyncGenerator<WorkflowStatusResult<unknown>, WorkflowStatusResult<unknown>, void>;
|
|
1751
|
-
/** Build the vendor-specific payload for a model without submitting. */
|
|
1752
|
-
buildPayload<M extends TypedModelId>(model: M, params: ModelInputById[M]): Record<string, unknown>;
|
|
1753
|
-
/** @deprecated Use `apis.run()` instead. Run a raw workflow (not tied to a model). */
|
|
1754
|
-
runWorkflow<TResult = unknown>(workflow: string, payload: Record<string, unknown>, options?: WorkflowRunOptions): Promise<TResult>;
|
|
1755
|
-
/**
|
|
1756
|
-
* Direct, low-level access to the Picsart model APIs — run any API by name.
|
|
1757
|
-
* See {@link ApisClient}.
|
|
1758
|
-
*/
|
|
1759
|
-
apis: ApisClient;
|
|
1760
|
-
/** Drive operations. Only available when drive config is provided. */
|
|
1761
|
-
drive: DriveClient | undefined;
|
|
1762
|
-
}
|
|
1763
|
-
|
|
1764
|
-
/**
|
|
1765
|
-
* Create an AI SDK client.
|
|
1766
|
-
*
|
|
1767
|
-
* @example Simple — pass an authenticated fetch:
|
|
1768
|
-
* ```ts
|
|
1769
|
-
* const ai = createClient({ fetch: myAuthenticatedFetch });
|
|
1770
|
-
* ```
|
|
1771
|
-
*
|
|
1772
|
-
* @example With Drive — auto-save generations:
|
|
1773
|
-
* ```ts
|
|
1774
|
-
* const ai = createClient({
|
|
1775
|
-
* fetch: myAuthenticatedFetch,
|
|
1776
|
-
* drive: { folder: 'AI Playground' },
|
|
1777
|
-
* });
|
|
1778
|
-
* ```
|
|
1779
|
-
*/
|
|
1780
|
-
declare function createClient(config: ClientConfig | SdkTransport): AiClient;
|
|
1781
|
-
|
|
1782
1636
|
interface ParamSchema {
|
|
1783
1637
|
type: 'string' | 'number' | 'boolean' | 'file';
|
|
1784
1638
|
enum?: (string | number)[];
|
|
@@ -1810,6 +1664,19 @@ interface EnumDescriptor<T extends string | number = string> {
|
|
|
1810
1664
|
options: Array<EnumOption<T>>;
|
|
1811
1665
|
default: T;
|
|
1812
1666
|
}
|
|
1667
|
+
/**
|
|
1668
|
+
* Free-string id served by a platform catalog task (voices/avatars). The id
|
|
1669
|
+
* space is open-ended — the live catalog is the source of truth — so the value
|
|
1670
|
+
* is validated only by type, never by membership. `source` says which task
|
|
1671
|
+
* serves the options; the entry's `catalogOptions` carries the seed (and,
|
|
1672
|
+
* after `ai.catalogs.voices/avatars`, the live list).
|
|
1673
|
+
*/
|
|
1674
|
+
interface CatalogDescriptor {
|
|
1675
|
+
kind: 'catalog';
|
|
1676
|
+
/** Platform catalog task that serves this param's live options. */
|
|
1677
|
+
source: CatalogSource;
|
|
1678
|
+
default: string;
|
|
1679
|
+
}
|
|
1813
1680
|
interface RangeDescriptor {
|
|
1814
1681
|
kind: 'range';
|
|
1815
1682
|
min: number;
|
|
@@ -1867,7 +1734,7 @@ interface ObjectDescriptor {
|
|
|
1867
1734
|
max?: number;
|
|
1868
1735
|
};
|
|
1869
1736
|
}
|
|
1870
|
-
type ParamDescriptor = EnumDescriptor<string> | EnumDescriptor<number> | RangeDescriptor | BooleanDescriptor | TextDescriptor | FileDescriptor | ObjectDescriptor;
|
|
1737
|
+
type ParamDescriptor = EnumDescriptor<string> | EnumDescriptor<number> | CatalogDescriptor | RangeDescriptor | BooleanDescriptor | TextDescriptor | FileDescriptor | ObjectDescriptor;
|
|
1871
1738
|
interface ParamEntry {
|
|
1872
1739
|
label?: string;
|
|
1873
1740
|
required?: boolean;
|
|
@@ -1894,6 +1761,7 @@ interface EntryMeta {
|
|
|
1894
1761
|
disabledReason?: string;
|
|
1895
1762
|
}
|
|
1896
1763
|
type EnumEntry = EntryMeta & EnumDescriptor<string | number>;
|
|
1764
|
+
type CatalogEntry = EntryMeta & CatalogDescriptor;
|
|
1897
1765
|
type RangeEntry = EntryMeta & RangeDescriptor;
|
|
1898
1766
|
type BooleanEntry = EntryMeta & BooleanDescriptor;
|
|
1899
1767
|
type TextEntry = EntryMeta & TextDescriptor;
|
|
@@ -1928,6 +1796,8 @@ interface ModelParamsAccessor {
|
|
|
1928
1796
|
hasParam(key: string): boolean;
|
|
1929
1797
|
all(): FlatParamEntry[];
|
|
1930
1798
|
enum(key: string): EnumEntry | undefined;
|
|
1799
|
+
/** Catalog params (`kind: 'catalog'`) — free-string ids; options live in `catalogOptions`. */
|
|
1800
|
+
catalog(key: string): CatalogEntry | undefined;
|
|
1931
1801
|
range(key: string): RangeEntry | undefined;
|
|
1932
1802
|
boolean(key: string): BooleanEntry | undefined;
|
|
1933
1803
|
text(key: string): TextEntry | undefined;
|
|
@@ -2194,6 +2064,259 @@ interface ModelDefinition {
|
|
|
2194
2064
|
testTimeout?: number;
|
|
2195
2065
|
}
|
|
2196
2066
|
|
|
2067
|
+
/**
|
|
2068
|
+
* Voice/avatar catalogs — the standard format served by the platform
|
|
2069
|
+
* `<vendor>/v1/catalog/<voices|avatars>` tasks, plus the in-memory hydration
|
|
2070
|
+
* registry that lets runtime-fetched catalogs back the descriptor system.
|
|
2071
|
+
*
|
|
2072
|
+
* The wire types mirror the shared backend contract (`@picsart/pa-genai-common`);
|
|
2073
|
+
* the SDK owns its own copy so it carries no backend dependency.
|
|
2074
|
+
*/
|
|
2075
|
+
|
|
2076
|
+
interface CatalogPreview {
|
|
2077
|
+
imageUrl?: string;
|
|
2078
|
+
videoUrl?: string;
|
|
2079
|
+
audioUrl?: string;
|
|
2080
|
+
}
|
|
2081
|
+
interface CatalogItem {
|
|
2082
|
+
/** Vendor-native id, sent back verbatim on generate (voiceId / videoId). */
|
|
2083
|
+
id: string;
|
|
2084
|
+
name: string;
|
|
2085
|
+
description?: string;
|
|
2086
|
+
/** Facets for filtering: gender, language, age, accent, tone, … */
|
|
2087
|
+
tags: string[];
|
|
2088
|
+
preview?: CatalogPreview;
|
|
2089
|
+
/** Vendor extras, e.g. `defaultVoiceId` on HeyGen avatars. */
|
|
2090
|
+
meta?: Record<string, unknown>;
|
|
2091
|
+
}
|
|
2092
|
+
interface CatalogQuery {
|
|
2093
|
+
/** Worker-side filter (e.g. the seed-audio model variant on bytedance). */
|
|
2094
|
+
modelId?: string;
|
|
2095
|
+
/** Opaque cursor from a previous page. */
|
|
2096
|
+
cursor?: string;
|
|
2097
|
+
/** Page size. Every catalog task accepts up to 100. */
|
|
2098
|
+
limit?: number;
|
|
2099
|
+
}
|
|
2100
|
+
interface CatalogResult {
|
|
2101
|
+
items: CatalogItem[];
|
|
2102
|
+
/** Crawl date or curation stamp identifying the snapshot. */
|
|
2103
|
+
version: string;
|
|
2104
|
+
/** How long the caller may cache this response. */
|
|
2105
|
+
ttlSeconds: number;
|
|
2106
|
+
/** `null` when the list is complete. */
|
|
2107
|
+
nextCursor: string | null;
|
|
2108
|
+
}
|
|
2109
|
+
type CatalogKind = 'voices' | 'avatars';
|
|
2110
|
+
/** Binds a param's options to a platform catalog task. */
|
|
2111
|
+
interface CatalogSource {
|
|
2112
|
+
/** Catalog workflow name, e.g. `heygen/v1/catalog/voices`. */
|
|
2113
|
+
workflow: string;
|
|
2114
|
+
/** Worker-side filter passed on fetch. */
|
|
2115
|
+
modelId?: string;
|
|
2116
|
+
}
|
|
2117
|
+
declare function toVoiceOption(item: CatalogItem, provider: Provider): VoiceOption;
|
|
2118
|
+
declare function toAvatarOption(item: CatalogItem, provider: Provider): AvatarOption;
|
|
2119
|
+
|
|
2120
|
+
/**
|
|
2121
|
+
* ai.catalogs — runtime access to the platform voice/avatar catalog tasks
|
|
2122
|
+
* (`<vendor>/v1/catalog/<voices|avatars>`).
|
|
2123
|
+
*
|
|
2124
|
+
* Loading is page-by-page: each call fetches ONE page (UI loads more on
|
|
2125
|
+
* scroll/pagination via `nextCursor`). Pages are cached per the `ttlSeconds`
|
|
2126
|
+
* the platform returns, concurrent fetches of the same page collapse, and
|
|
2127
|
+
* every fetched page is appended to the options installed on the model so
|
|
2128
|
+
* `Model(id).params()` (and every picker built on it) sees what has been
|
|
2129
|
+
* loaded so far. With `createClient({ catalogs: { preload: true } })` the
|
|
2130
|
+
* first page of every bound catalog loads in the background at client
|
|
2131
|
+
* creation.
|
|
2132
|
+
*/
|
|
2133
|
+
|
|
2134
|
+
/** Model id with autocomplete that still accepts arbitrary strings. */
|
|
2135
|
+
type ModelId = TypedModelId | (string & {});
|
|
2136
|
+
/** One fetched page. Pass `nextCursor` back to load the next one. */
|
|
2137
|
+
interface CatalogPage {
|
|
2138
|
+
items: CatalogItem[];
|
|
2139
|
+
/** `null` when the list is complete. */
|
|
2140
|
+
nextCursor: string | null;
|
|
2141
|
+
}
|
|
2142
|
+
interface CatalogPageOptions {
|
|
2143
|
+
/** Cursor from the previous page's `nextCursor`; omit for the first page. */
|
|
2144
|
+
cursor?: string;
|
|
2145
|
+
/** Page size, 1..100. Defaults to 100. */
|
|
2146
|
+
limit?: number;
|
|
2147
|
+
/** Drop everything cached for this catalog and refetch from the first page. */
|
|
2148
|
+
forceRefresh?: boolean;
|
|
2149
|
+
/**
|
|
2150
|
+
* Cancels this caller's wait only. A fetch shared with other callers keeps
|
|
2151
|
+
* running so its result can still be cached for them.
|
|
2152
|
+
*/
|
|
2153
|
+
signal?: AbortSignal;
|
|
2154
|
+
}
|
|
2155
|
+
interface CatalogsClient {
|
|
2156
|
+
/**
|
|
2157
|
+
* One page of the model's voice catalog. Fetched pages accumulate into the
|
|
2158
|
+
* model's `voiceId` options, so pickers see everything loaded so far.
|
|
2159
|
+
*/
|
|
2160
|
+
voices(model: ModelId, options?: CatalogPageOptions): Promise<CatalogPage>;
|
|
2161
|
+
/** One page of the model's avatar catalog — same semantics, for `videoId`. */
|
|
2162
|
+
avatars(model: ModelId, options?: CatalogPageOptions): Promise<CatalogPage>;
|
|
2163
|
+
}
|
|
2164
|
+
interface CatalogsOptions {
|
|
2165
|
+
/**
|
|
2166
|
+
* Load the first page of every catalog-bound param in the background at
|
|
2167
|
+
* client creation, so pickers open with data before any explicit call.
|
|
2168
|
+
*/
|
|
2169
|
+
preload?: boolean;
|
|
2170
|
+
}
|
|
2171
|
+
|
|
2172
|
+
/** A fetch-like function that handles authentication (headers, cookies, etc.). */
|
|
2173
|
+
type AuthenticatedFetch = (url: string, init?: RequestInit) => Promise<Response>;
|
|
2174
|
+
/** Drive configuration — enables auto-saving generations to Picsart Drive. */
|
|
2175
|
+
interface DriveConfig {
|
|
2176
|
+
/** Root folder name in Drive. All generations save here. */
|
|
2177
|
+
folder: string;
|
|
2178
|
+
}
|
|
2179
|
+
/**
|
|
2180
|
+
* Whether the embedding app is a native client or a miniapp. Set backend-side
|
|
2181
|
+
* during save; surfaced read-only via `getGeneration`.
|
|
2182
|
+
*/
|
|
2183
|
+
type AppType = 'native' | 'miniapp';
|
|
2184
|
+
/**
|
|
2185
|
+
* App identity (appId + appType).
|
|
2186
|
+
* TODO(backend-autosave): temporary — the backend will stamp appId/appType on
|
|
2187
|
+
* save. Until then apps may pass this so it's persisted client-side.
|
|
2188
|
+
*/
|
|
2189
|
+
interface AppIdentity {
|
|
2190
|
+
id: string;
|
|
2191
|
+
type: AppType;
|
|
2192
|
+
}
|
|
2193
|
+
/**
|
|
2194
|
+
* Simple client config — pass the API base URL plus one auth source, and the
|
|
2195
|
+
* SDK handles the rest. The SDK knows the Picsart API endpoints and response
|
|
2196
|
+
* shapes internally.
|
|
2197
|
+
*
|
|
2198
|
+
* Provide exactly one of:
|
|
2199
|
+
* - `fetch` — your own authenticated fetch (you add headers/cookies), or
|
|
2200
|
+
* - `apiKey` — the SDK builds a fetch that sends `Authorization: Bearer <apiKey>`.
|
|
2201
|
+
*/
|
|
2202
|
+
interface ClientConfig {
|
|
2203
|
+
/**
|
|
2204
|
+
* Authenticated fetch function. The SDK calls this for all HTTP requests.
|
|
2205
|
+
* Provide this or `apiKey`. Takes precedence over `apiKey` when both are set.
|
|
2206
|
+
*/
|
|
2207
|
+
fetch?: AuthenticatedFetch;
|
|
2208
|
+
/**
|
|
2209
|
+
* Picsart API key. When `fetch` is not provided, the SDK builds an
|
|
2210
|
+
* authenticated fetch that sends `Authorization: Bearer <apiKey>` on every
|
|
2211
|
+
* request (a leading `Bearer ` is stripped if present).
|
|
2212
|
+
*/
|
|
2213
|
+
apiKey?: string;
|
|
2214
|
+
/** API base URL (e.g. 'https://api.picsart.com'). */
|
|
2215
|
+
apiUrl: string;
|
|
2216
|
+
/** Enable Drive integration — auto-save generations to a Drive folder. */
|
|
2217
|
+
drive?: DriveConfig;
|
|
2218
|
+
/**
|
|
2219
|
+
* Voice/avatar catalog behavior. `{ preload: true }` loads the first page
|
|
2220
|
+
* of every catalog-bound param in the background at client creation.
|
|
2221
|
+
*/
|
|
2222
|
+
catalogs?: CatalogsOptions;
|
|
2223
|
+
}
|
|
2224
|
+
interface GenerateResultItem {
|
|
2225
|
+
url: string;
|
|
2226
|
+
metadata?: Record<string, unknown>;
|
|
2227
|
+
}
|
|
2228
|
+
interface GenerateResult {
|
|
2229
|
+
/** Primary result URL (convenience shortcut for results[0].url). */
|
|
2230
|
+
url: string;
|
|
2231
|
+
/** All result items — single item for normal models, multiple for explore/multi-result models. */
|
|
2232
|
+
results: GenerateResultItem[];
|
|
2233
|
+
/** Model ID that produced this result. */
|
|
2234
|
+
model: string;
|
|
2235
|
+
/** Job handle for status tracking. */
|
|
2236
|
+
handle: WorkflowJobHandle;
|
|
2237
|
+
/** Raw parsed output for advanced consumers. */
|
|
2238
|
+
raw: unknown;
|
|
2239
|
+
/** Present when Drive is enabled and the file was saved. */
|
|
2240
|
+
drive?: DriveSaveResult;
|
|
2241
|
+
}
|
|
2242
|
+
/** Result of a text-generation (LLM) model. */
|
|
2243
|
+
interface GenerateTextResult {
|
|
2244
|
+
/** Generated text. */
|
|
2245
|
+
text: string;
|
|
2246
|
+
/** Model ID that produced this result. */
|
|
2247
|
+
model: string;
|
|
2248
|
+
/** Job handle for status tracking. */
|
|
2249
|
+
handle: WorkflowJobHandle;
|
|
2250
|
+
/** Raw parsed output — carries usage, finish reason, thinking trace, etc. */
|
|
2251
|
+
raw: unknown;
|
|
2252
|
+
}
|
|
2253
|
+
/** Options for individual generate() / submit() calls. */
|
|
2254
|
+
interface GenerateOptions {
|
|
2255
|
+
signal?: AbortSignal;
|
|
2256
|
+
/** Save to a specific subfolder instead of the root (legacy — used by SDK DriveConfig). */
|
|
2257
|
+
folder?: DriveFolder;
|
|
2258
|
+
/** Save result to Picsart Drive via backend. Injected into the workflow payload. */
|
|
2259
|
+
drive?: PayloadDriveOptions;
|
|
2260
|
+
/**
|
|
2261
|
+
* App identity stamped onto the saved generation (appId/appType).
|
|
2262
|
+
* TODO(backend-autosave): temporary — remove once the backend stamps these.
|
|
2263
|
+
*/
|
|
2264
|
+
app?: AppIdentity;
|
|
2265
|
+
}
|
|
2266
|
+
/** Non-text (image/video/audio) model IDs — the media generation surface. */
|
|
2267
|
+
type MediaModelId = Exclude<TypedModelId, TextModelId>;
|
|
2268
|
+
/** AI SDK client with type-safe, model-aware method signatures. */
|
|
2269
|
+
interface AiClient {
|
|
2270
|
+
/** Generate content using a media model. Text/LLM models use generateText(). */
|
|
2271
|
+
generate<M extends MediaModelId>(model: M, params: ModelInputById[M], options?: GenerateOptions): Promise<GenerateResult>;
|
|
2272
|
+
/** Generate text using an LLM model. Returns the generated text plus the raw response. */
|
|
2273
|
+
generateText<M extends TextModelId>(model: M, params: TextModelInputById[M], options?: GenerateOptions): Promise<GenerateTextResult>;
|
|
2274
|
+
/** Get exact credit cost for a model with specific parameters. */
|
|
2275
|
+
getCredits<M extends TypedModelId>(model: M, params: ModelInputById[M]): Promise<number | null>;
|
|
2276
|
+
/** Submit a generation job and get a handle back. Media models only. */
|
|
2277
|
+
submit<M extends MediaModelId>(model: M, params: ModelInputById[M], options?: GenerateOptions): Promise<WorkflowJobHandle>;
|
|
2278
|
+
/** Check the current status of a submitted job. */
|
|
2279
|
+
status(handle: WorkflowJobHandle, signal?: AbortSignal): Promise<WorkflowStatusResult<unknown>>;
|
|
2280
|
+
/** Poll a submitted job until it completes and return the parsed result. Media models only. */
|
|
2281
|
+
result(handle: WorkflowJobHandle, model: MediaModelId, options?: WorkflowPollOptions): Promise<GenerateResult>;
|
|
2282
|
+
/** Subscribe to live status updates for a submitted job. */
|
|
2283
|
+
subscribe(handle: WorkflowJobHandle, options?: WorkflowSubscribeOptions): AsyncGenerator<WorkflowStatusResult<unknown>, WorkflowStatusResult<unknown>, void>;
|
|
2284
|
+
/** Build the vendor-specific payload for a model without submitting. */
|
|
2285
|
+
buildPayload<M extends TypedModelId>(model: M, params: ModelInputById[M]): Record<string, unknown>;
|
|
2286
|
+
/** @deprecated Use `apis.run()` instead. Run a raw workflow (not tied to a model). */
|
|
2287
|
+
runWorkflow<TResult = unknown>(workflow: string, payload: Record<string, unknown>, options?: WorkflowRunOptions): Promise<TResult>;
|
|
2288
|
+
/**
|
|
2289
|
+
* Direct, low-level access to the Picsart model APIs — run any API by name.
|
|
2290
|
+
* See {@link ApisClient}.
|
|
2291
|
+
*/
|
|
2292
|
+
apis: ApisClient;
|
|
2293
|
+
/**
|
|
2294
|
+
* Voice/avatar catalogs served by the platform catalog tasks — fetch,
|
|
2295
|
+
* ttl-cache, and hydrate model params. See {@link CatalogsClient}.
|
|
2296
|
+
*/
|
|
2297
|
+
catalogs: CatalogsClient;
|
|
2298
|
+
/** Drive operations. Only available when drive config is provided. */
|
|
2299
|
+
drive: DriveClient | undefined;
|
|
2300
|
+
}
|
|
2301
|
+
|
|
2302
|
+
/**
|
|
2303
|
+
* Create an AI SDK client.
|
|
2304
|
+
*
|
|
2305
|
+
* @example Simple — pass an authenticated fetch:
|
|
2306
|
+
* ```ts
|
|
2307
|
+
* const ai = createClient({ fetch: myAuthenticatedFetch });
|
|
2308
|
+
* ```
|
|
2309
|
+
*
|
|
2310
|
+
* @example With Drive — auto-save generations:
|
|
2311
|
+
* ```ts
|
|
2312
|
+
* const ai = createClient({
|
|
2313
|
+
* fetch: myAuthenticatedFetch,
|
|
2314
|
+
* drive: { folder: 'AI Playground' },
|
|
2315
|
+
* });
|
|
2316
|
+
* ```
|
|
2317
|
+
*/
|
|
2318
|
+
declare function createClient(config: ClientConfig | SdkTransport): AiClient;
|
|
2319
|
+
|
|
2197
2320
|
/**
|
|
2198
2321
|
* Typed Models constants and namespace.
|
|
2199
2322
|
* Regenerate with: npm run build:model-constants
|
|
@@ -2316,8 +2439,6 @@ declare const Models: {
|
|
|
2316
2439
|
readonly Lyria3Pro: "lyria-3-pro";
|
|
2317
2440
|
readonly Minimax02Hd: "minimax-02-hd";
|
|
2318
2441
|
readonly MinimaxMusicV2: "minimax-music-v2";
|
|
2319
|
-
readonly OpenaiTts1: "openai-tts-1";
|
|
2320
|
-
readonly OpenaiTts1Hd: "openai-tts-1-hd";
|
|
2321
2442
|
readonly Ovi: "ovi";
|
|
2322
2443
|
readonly PicsartChangeBg: "picsart-change-bg";
|
|
2323
2444
|
readonly PicsartEnhance: "picsart-enhance";
|
|
@@ -2428,7 +2549,15 @@ declare const Models: {
|
|
|
2428
2549
|
readonly hasParam: (id: string, key: string) => boolean;
|
|
2429
2550
|
};
|
|
2430
2551
|
|
|
2431
|
-
|
|
2552
|
+
/**
|
|
2553
|
+
* Default voice ids for the catalog-bound TTS params. The voice LISTS are not
|
|
2554
|
+
* bundled: options come from the platform catalog tasks at runtime
|
|
2555
|
+
* (`ai.catalogs.voices`) — the workers cache them and answer fast.
|
|
2556
|
+
*/
|
|
2557
|
+
|
|
2558
|
+
declare function getVoiceById(id: string): VoiceOption | undefined;
|
|
2559
|
+
/** @deprecated Load the model's catalog instead (`ai.catalogs.voices(modelId)`) — loaded voices are searched automatically. */
|
|
2560
|
+
declare function getVoiceById(id: string, extra: VoiceOption[] | undefined): VoiceOption | undefined;
|
|
2432
2561
|
|
|
2433
2562
|
/**
|
|
2434
2563
|
* Pricing internals — owns the ModelPricingClient, the per-model cache, and
|
|
@@ -2553,4 +2682,4 @@ declare const findModel: (ref: string) => ModelDefinition | undefined;
|
|
|
2553
2682
|
/** Effect scenes that require two input images (e.g. hugs, kisses, swaps). */
|
|
2554
2683
|
declare const KLING_DUAL_IMAGE_EFFECTS: ReadonlySet<string>;
|
|
2555
2684
|
|
|
2556
|
-
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 };
|
|
2685
|
+
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 CatalogDescriptor, type CatalogEntry, type CatalogItem, type CatalogKind, type CatalogPage, type CatalogPageOptions, type CatalogPreview, type CatalogQuery, type CatalogResult, type CatalogSource, type CatalogsClient, type CatalogsOptions, 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, toAvatarOption, toVoiceOption };
|