@picsart/ai-sdk 5.24.0 → 5.25.0

package/index.d.ts

@@ -49,6 +49,10 @@ interface WorkflowStatusResult<TResult = unknown> {
     status: WorkflowStatus;
     result?: TResult;
     error?: string;
+    /** Platform error `reason` on a failed task, when the response carried one. */
+    reason?: string;
+    /** Numeric status on the error payload, when the response carried one. */
+    statusCode?: number;
     progress?: WorkflowProgress;
     /** Credit usage reported by the platform, when present on the response. */
     usage?: CreditUsage;
@@ -822,6 +826,18 @@ type ModelInputById = {
         bitrate?: 32000 | 64000 | 128000 | 256000;
         format?: "mp3" | "wav" | "pcm";
     };
+    "muse-image-1.0": {
+        prompt: string;
+        aspectRatio?: "1:1" | "3:2" | "2:3" | "16:9" | "9:16" | "4:3" | "3:4";
+        reasoningStrength?: "low" | "high";
+        moderation?: "auto" | "low" | "none";
+        enableImageSearch?: boolean;
+        enableWebSearch?: boolean;
+        enableShell?: boolean;
+        outputFormat?: "png" | "jpeg" | "webp";
+        count?: 1 | 2 | 4 | 6 | 8 | 10;
+        imageUrls?: string[];
+    };
     "ovi": {
         prompt: string;
         size?: "9:16" | "16:9" | "1:1" | "9:16+" | "16:9+" | "2:5" | "5:2";
@@ -2026,7 +2042,7 @@ interface ModelFilter$1 {
     release?: ReleaseTag[];
 }
 
-type AppProvider = 'picsart' | 'google' | 'kling' | 'grok' | 'openai' | 'flux' | 'ideogram' | 'elevenlabs' | 'minimax' | 'wan' | 'seedance' | 'ltx' | 'seedream' | 'seedaudio' | 'hunyuan' | 'pika' | 'runway' | 'luma' | 'ovi' | 'creatify' | 'veed' | 'bytedance' | 'qwen' | 'reve' | 'recraft' | 'videography' | 'topaz' | 'heygen' | 'happyhorse' | 'pixverse' | 'anthropic' | 'async' | 'captionsai';
+type AppProvider = 'picsart' | 'google' | 'kling' | 'grok' | 'openai' | 'flux' | 'ideogram' | 'elevenlabs' | 'minimax' | 'wan' | 'seedance' | 'ltx' | 'seedream' | 'seedaudio' | 'hunyuan' | 'pika' | 'runway' | 'luma' | 'ovi' | 'creatify' | 'veed' | 'bytedance' | 'qwen' | 'reve' | 'recraft' | 'videography' | 'topaz' | 'heygen' | 'happyhorse' | 'pixverse' | 'anthropic' | 'async' | 'captionsai' | 'meta';
 /** Provider used by model definitions. */
 type Provider = AppProvider;
 /** App generation modes. */
@@ -2631,6 +2647,7 @@ declare const Models: {
     readonly MinimaxH3Max: "minimax-h3-max";
     readonly MinimaxMusicV2: "minimax-music-v2";
     readonly MinimaxMusicV3: "minimax-music-v3";
+    readonly MuseImage10: "muse-image-1.0";
     readonly Ovi: "ovi";
     readonly PicsartChangeBg: "picsart-change-bg";
     readonly PicsartEnhance: "picsart-enhance";
@@ -2761,6 +2778,59 @@ declare function getVoiceById(id: string): VoiceOption | undefined;
 /** @deprecated Load the model's catalog instead (`ai.catalogs.voices(modelId)`) — loaded voices are searched automatically. */
 declare function getVoiceById(id: string, extra: VoiceOption[] | undefined): VoiceOption | undefined;
 
+/**
+ * Failure codes the SDK synthesizes when the platform supplies no `reason`.
+ * An API-supplied `reason` passes through unchanged, so the open `string`
+ * member keeps arbitrary platform reasons assignable while preserving
+ * autocomplete on the known set.
+ */
+type ApiErrorCode = 'unknown_model' | 'wrong_model_mode' | 'validation_error' | 'unsupported_transport' | 'timeout' | 'aborted' | 'canceled' | 'generation_failed' | 'invalid_response' | 'bad_request' | 'unauthorized' | 'payment_required' | 'forbidden' | 'not_found' | 'rate_limited' | 'server_error' | (string & {});
+/** Everything but the message needed to build a {@link ApiError}. */
+interface ApiErrorInit {
+    /**
+     * HTTP status of the failing response. When no HTTP exchange took place the
+     * SDK synthesizes the semantically matching code: 400 for input the SDK
+     * itself rejects, 408 for a poll deadline, 499 for an abort or cancel, 502
+     * for a response it cannot make sense of.
+     */
+    status: number;
+    /** Platform `reason` when present, otherwise an SDK-synthesized code. */
+    code: ApiErrorCode;
+}
+/**
+ * The single error type thrown by the SDK's generation surface —
+ * `generate()`, `generateText()`, `submit()`, and `result()`.
+ *
+ * Unrelated to the `Api*` types (`ApiResponse`, `ApiRunOptions`, …), which
+ * describe the low-level `ai.apis` surface. `ai.apis.run()` throws the
+ * workflows client's own errors, not this.
+ *
+ * ```ts
+ * try {
+ *   await ai.generate(Models.Flux2Pro, { prompt: 'a cat' });
+ * } catch (err) {
+ *   if (err instanceof ApiError) {
+ *     if (err.status === 402) return topUpCredits();
+ *     if (err.status === 429 || err.status >= 500) return retry();
+ *     if (err.code === 'validation_error') return showFormError(err.message);
+ *   }
+ *   throw err;
+ * }
+ * ```
+ *
+ * Aborts raised by `fetch` itself are never wrapped — a caller checking
+ * `err.name === 'AbortError'` on a `DOMException` keeps working.
+ */
+declare class ApiError extends Error {
+    /** HTTP status, or the synthesized equivalent for non-HTTP failures. */
+    readonly status: number;
+    /** Platform `reason`, or an SDK-synthesized code. Always equal to {@link reason}. */
+    readonly code: ApiErrorCode;
+    /** Alias of {@link code}, named after the platform's own error field. */
+    readonly reason: ApiErrorCode;
+    constructor(message: string, init: ApiErrorInit);
+}
+
 /**
  * Pricing internals — owns the ModelPricingClient, the per-model cache, and
  * the credit-range lookup. The Model accessor delegates to the helpers below
@@ -2889,4 +2959,4 @@ declare const findModel: (ref: string) => ModelDefinition | undefined;
  */
 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 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, type CreditTier, type CreditUsage, 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 ToolUsage, 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 };
+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 CatalogKind, 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 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 ToolUsage, 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 };

package/index.js

@@ -441,6 +441,62 @@ var require_build = __commonJS({
   }
 });
 
+// src/core/errors.ts
+var ApiError = class extends Error {
+  /** HTTP status, or the synthesized equivalent for non-HTTP failures. */
+  status;
+  /** Platform `reason`, or an SDK-synthesized code. Always equal to {@link reason}. */
+  code;
+  /** Alias of {@link code}, named after the platform's own error field. */
+  reason;
+  constructor(message, init) {
+    super(message);
+    this.name = "ApiError";
+    this.status = init.status;
+    this.code = init.code;
+    this.reason = init.code;
+  }
+};
+var CODE_BY_STATUS = {
+  400: "bad_request",
+  401: "unauthorized",
+  402: "payment_required",
+  403: "forbidden",
+  404: "not_found",
+  408: "timeout",
+  409: "conflict",
+  413: "payload_too_large",
+  422: "unprocessable_entity",
+  429: "rate_limited",
+  500: "server_error",
+  502: "bad_gateway",
+  503: "service_unavailable",
+  504: "gateway_timeout"
+};
+function codeForStatus(status) {
+  return CODE_BY_STATUS[status] ?? (status >= 500 ? "server_error" : `http_${status}`);
+}
+async function readErrorBody(res) {
+  let text = "";
+  try {
+    text = await res.text();
+  } catch {
+    return { text: "" };
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return { text, json: parsed };
+    }
+  } catch {
+  }
+  return { text };
+}
+function reasonFrom(json, status) {
+  const raw = json?.reason ?? json?.code;
+  return typeof raw === "string" && raw.length > 0 ? raw : codeForStatus(status);
+}
+
 // src/core/workflow.ts
 var DEFAULT_POLL_INTERVAL_MS = 2e3;
 var DEFAULT_MAX_ATTEMPTS = 300;
@@ -476,7 +532,9 @@ function parseWorkflowStatus(handle, raw) {
   const result = pickFirst(raw, [["response", "result"], ["result"]]);
   const usageRaw = pickFirst(raw, [["response", "usage"], ["usage"]]);
   const usage = usageRaw && typeof usageRaw === "object" && (typeof usageRaw.credits === "number" || Array.isArray(usageRaw.details)) ? usageRaw : void 0;
-  const errorRaw = pickFirst(raw, [["response", "error"], ["error"], ["message"], ["reason"]]);
+  const errorRaw = pickFirst(raw, [["response", "error"], ["response", "message"], ["error"], ["message"], ["reason"]]);
+  const reasonRaw = pickFirst(raw, [["response", "reason"], ["reason"]]);
+  const statusCodeRaw = pickFirst(raw, [["response", "statusCode"], ["statusCode"]]);
   const progressRaw = pickFirst(raw, [["response", "progress"], ["progress"]]);
   const progress = progressRaw && typeof progressRaw === "object" ? {
     percent: typeof progressRaw.percent === "number" ? progressRaw.percent : void 0,
@@ -487,6 +545,8 @@ function parseWorkflowStatus(handle, raw) {
     status,
     result,
     error: typeof errorRaw === "string" ? errorRaw : void 0,
+    reason: typeof reasonRaw === "string" ? reasonRaw : void 0,
+    statusCode: typeof statusCodeRaw === "number" ? statusCodeRaw : void 0,
     progress,
     usage,
     raw
@@ -502,13 +562,19 @@ function createWorkflowClient(transport, options = {}) {
   const defaultMaxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
   const submit = async (request) => {
     if (!transport.submit) {
-      throw new Error("Transport does not support submit (execute-only transport)");
+      throw new ApiError("Transport does not support submit (execute-only transport)", {
+        status: 400,
+        code: "unsupported_transport"
+      });
     }
     return transport.submit(request);
   };
   const status = async (handle, signal) => {
     if (!transport.status) {
-      throw new Error("Transport does not support status (execute-only transport)");
+      throw new ApiError("Transport does not support status (execute-only transport)", {
+        status: 400,
+        code: "unsupported_transport"
+      });
     }
     const raw = await transport.status(handle, signal);
     return parseStatus(handle, raw);
@@ -518,13 +584,16 @@ function createWorkflowClient(transport, options = {}) {
     const maxAttempts = pollOptions.maxAttempts ?? defaultMaxAttempts;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       if (pollOptions.signal?.aborted) {
-        throw new Error("Operation aborted");
+        throw new ApiError("Operation aborted", { status: 499, code: "aborted" });
       }
       const next = await status(handle, pollOptions.signal);
       if (isTerminal(next.status)) return next;
       await sleep2(intervalMs);
     }
-    throw new Error(`Timed out waiting for workflow ${handle.workflow}:${handle.id}`);
+    throw new ApiError(
+      `Timed out waiting for workflow ${handle.workflow}:${handle.id}`,
+      { status: 408, code: "timeout" }
+    );
   };
   const run = async (request, runOptions = {}) => {
     const runMode = runOptions.mode;
@@ -543,14 +612,17 @@ function createWorkflowClient(transport, options = {}) {
     const maxAttempts = subscribeOptions.maxAttempts ?? defaultMaxAttempts;
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
       if (subscribeOptions.signal?.aborted) {
-        throw new Error("Operation aborted");
+        throw new ApiError("Operation aborted", { status: 499, code: "aborted" });
       }
       const next = await status(handle, subscribeOptions.signal);
       yield next;
       if (isTerminal(next.status)) return next;
       await sleep2(intervalMs);
     }
-    throw new Error(`Timed out waiting for workflow ${handle.workflow}:${handle.id}`);
+    throw new ApiError(
+      `Timed out waiting for workflow ${handle.workflow}:${handle.id}`,
+      { status: 408, code: "timeout" }
+    );
   };
   return { submit, status, result, run, subscribe };
 }
@@ -821,7 +893,8 @@ var providers = {
   pixverse: { color: "#7C3AED", label: "PV", name: "PixVerse" },
   anthropic: { color: "#D97757", label: "CL", name: "Anthropic" },
   async: { color: "#5E5CE6", label: "AA", name: "Async AI" },
-  captionsai: { color: "#1D1F20", label: "MR", name: "Mirage" }
+  captionsai: { color: "#1D1F20", label: "MR", name: "Mirage" },
+  meta: { color: "#0081FB", label: "MT", name: "Meta" }
 };
 
 // src/core/descriptors/presets.ts
@@ -1177,7 +1250,7 @@ var passthroughPayload = (paramConfig) => (ctx) => {
   return payload;
 };
 function defineModels(provider, configs) {
-  const MODELS38 = [];
+  const MODELS39 = [];
   for (const c of configs) {
     const prov = c.provider ?? provider;
     const resolvedPayload = c.buildPayload ?? passthroughPayload(c.paramConfig);
@@ -1213,19 +1286,19 @@ function defineModels(provider, configs) {
     if (c.constraints !== void 0) model.constraints = c.constraints;
     const contract = createModelContract(model);
     model.outputSchema = c.outputSchema ?? contract.output;
-    MODELS38.push(model);
+    MODELS39.push(model);
   }
-  return { MODELS: MODELS38 };
+  return { MODELS: MODELS39 };
 }
-function registerPayloads(MODELS38, payloads) {
+function registerPayloads(MODELS39, payloads) {
   for (const [id, builder] of Object.entries(payloads)) {
-    const model = MODELS38.find((m) => m.id === id);
+    const model = MODELS39.find((m) => m.id === id);
     if (model) model.buildPayload = builder;
   }
 }
-function registerEditPayloads(MODELS38, payloads) {
+function registerEditPayloads(MODELS39, payloads) {
   for (const [id, builder] of Object.entries(payloads)) {
-    const model = MODELS38.find((m) => m.id === id);
+    const model = MODELS39.find((m) => m.id === id);
     if (model) model.buildEditPayload = builder;
   }
 }
@@ -8561,6 +8634,74 @@ registerPayloads(MODELS37, {
   "captionsai-video-captions": buildCaptionsPayload
 });
 
+// src/vendors/catalog/meta.ts
+var { MODELS: MODELS38 } = defineModels("meta", [
+  // ── Image ─────────────────────────────────────────
+  {
+    id: "muse-image-1.0",
+    name: "Muse Image 1.0",
+    addedAt: "2026-08-31",
+    workflow: "meta/v1/images/generations",
+    editWorkflow: "meta/v1/images/edits",
+    estimatedTime: 60,
+    mode: "image",
+    inputType: "t2i",
+    description: "Meta's agentic image model \u2014 plans with reasoning, web and image search before rendering.",
+    features: [feat("Multi-Image Input", "input"), feat("Web Search", "characteristic"), feat("High Quality", "quality")],
+    paramConfig: {
+      ...params.prompt(),
+      ...params.aspectRatio(["1:1", "3:2", "2:3", "16:9", "9:16", "4:3", "3:4"], "1:1"),
+      // Vendor-side reasoning tier for the agentic planner; vendor default high.
+      ...p.enum("reasoningStrength", ["low", "high"], "high", { label: "Reasoning" }),
+      ...p.enum("moderation", ["auto", "low", "none"], "auto", { label: "Moderation" }),
+      // Per-tool planner controls — all-true matches the vendor default
+      // (omitting tool_enablement enables every tool).
+      ...p.boolean("enableImageSearch", true, "Image Search"),
+      ...p.boolean("enableWebSearch", true, "Web Search"),
+      ...p.boolean("enableShell", true, "Layout & Chart Tools"),
+      ...p.enum("outputFormat", ["png", "jpeg", "webp"], "png", { label: "Format" }),
+      ...params.count(),
+      ...params.imageInput(5, "Source Images")
+    }
+  }
+]);
+
+// src/vendors/catalog/meta.payloads.ts
+var MUSE_AR_TO_SIZE = {
+  "1:1": "1024x1024",
+  "3:2": "1536x1024",
+  "2:3": "1024x1536",
+  "16:9": "1820x1024",
+  "9:16": "1024x1820",
+  "4:3": "1365x1024",
+  "3:4": "1024x1365"
+};
+var buildMuseCommonPayload = (input) => ({
+  model: "muse-image-1.0",
+  prompt: input.prompt,
+  n: input.count ?? 1,
+  size: MUSE_AR_TO_SIZE[input.aspectRatio ?? ""] ?? "1024x1024",
+  ...input.outputFormat ? { output_format: input.outputFormat } : {},
+  ...input.reasoningStrength ? { reasoning_strength: input.reasoningStrength } : {},
+  ...input.moderation ? { moderation: input.moderation } : {},
+  tool_enablement: {
+    enable_image_search: input.enableImageSearch ?? true,
+    enable_web_search: input.enableWebSearch ?? true,
+    enable_shell: input.enableShell ?? true
+  }
+});
+var buildMuseImagePayload = (input) => buildMuseCommonPayload(input);
+var buildMuseImageEditPayload = (input) => ({
+  ...buildMuseCommonPayload(input),
+  images: input.imageUrls ?? []
+});
+registerPayloads(MODELS38, {
+  "muse-image-1.0": buildMuseImagePayload
+});
+registerEditPayloads(MODELS38, {
+  "muse-image-1.0": buildMuseImageEditPayload
+});
+
 // src/vendors/catalog/index.ts
 var ALL_MODELS = [
   ...MODELS,
@@ -8599,21 +8740,30 @@ var ALL_MODELS = [
   ...MODELS34,
   ...MODELS35,
   ...MODELS36,
-  ...MODELS37
+  ...MODELS37,
+  ...MODELS38
 ];
 var getModelsByMode = (mode, includeDisabled = false) => ALL_MODELS.filter((m) => m.mode === mode && (includeDisabled || isVisibleForReleases(m)));
 
 // src/core/contracts.ts
 function requireObject(value, message) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
-    throw new Error(message);
+    throw new ApiError(message, { status: 400, code: "validation_error" });
   }
 }
 function buildInputSchema(model) {
   return {
     parse(input) {
       requireObject(input, `Invalid input for model "${model.id}"`);
-      validateAll(model.paramConfig, input);
+      try {
+        validateAll(model.paramConfig, input);
+      } catch (err) {
+        if (err instanceof ApiError) throw err;
+        throw new ApiError(err instanceof Error ? err.message : String(err), {
+          status: 400,
+          code: "validation_error"
+        });
+      }
       return input;
     }
   };
@@ -8622,7 +8772,10 @@ function buildOutputSchema(model) {
   return {
     parse(output) {
       if (output == null) {
-        throw new Error(`Model "${model.id}" returned empty output`);
+        throw new ApiError(`Model "${model.id}" returned empty output`, {
+          status: 502,
+          code: "invalid_response"
+        });
       }
       return output;
     }
@@ -8665,7 +8818,12 @@ function throwIfErrorResult(result, modelName) {
   if (isError) {
     const code = typeof status === "number" ? ` (${status})` : "";
     const detail = message ? String(message) : "unknown error";
-    throw new Error(`${modelName} failed${code}: ${detail}`);
+    const httpStatus = typeof status === "number" ? status : 502;
+    const reason = obj.reason;
+    throw new ApiError(`${modelName} failed${code}: ${detail}`, {
+      status: httpStatus,
+      code: typeof reason === "string" && reason.length > 0 ? reason : codeForStatus(httpStatus)
+    });
   }
 }
 function extractSyncResult(raw) {
@@ -8867,7 +9025,9 @@ var findModel = (ref) => {
 // src/core/resolve.ts
 function resolveModel(id) {
   const found = findModel(id);
-  if (!found) throw new Error(`Unknown model: "${id}"`);
+  if (!found) {
+    throw new ApiError(`Unknown model: "${id}"`, { status: 400, code: "unknown_model" });
+  }
   return found;
 }
 
@@ -8907,18 +9067,34 @@ function buildTransport(config) {
         { params: request.payload },
         request.signal
       );
-      const data = await res.json();
+      const { text, json } = await readErrorBody(res);
       if (!res.ok) {
-        throw new Error(`Submit failed (${res.status}): ${data.message ?? JSON.stringify(data)}`);
+        const detail = json ? json.message ?? JSON.stringify(json) : text;
+        throw new ApiError(`Submit failed (${res.status}): ${detail}`, {
+          status: res.status,
+          code: reasonFrom(json, res.status)
+        });
+      }
+      const response = json?.response;
+      const id = response?.id ?? json?.id;
+      if (!id) {
+        throw new ApiError(`No task id in response: ${json ? JSON.stringify(json) : text}`, {
+          status: 502,
+          code: "invalid_response"
+        });
       }
-      const response = data.response;
-      const id = response?.id ?? data.id;
-      if (!id) throw new Error(`No task id in response: ${JSON.stringify(data)}`);
       return { workflow: request.workflow, id: String(id) };
     },
     async status(handle, signal) {
       const res = await f(`${apiUrl}/workflows/${handle.workflow}/${handle.id}/result`, { signal });
-      if (!res.ok) throw new Error(`Status check failed (${res.status}): ${await res.text()}`);
+      if (!res.ok) {
+        const { text, json } = await readErrorBody(res);
+        const detail = json ? json.message ?? text : text;
+        throw new ApiError(`Status check failed (${res.status}): ${detail}`, {
+          status: res.status,
+          code: reasonFrom(json, res.status)
+        });
+      }
       return res.json();
     },
     async execute(request) {
@@ -8927,7 +9103,14 @@ function buildTransport(config) {
         { params: request.payload },
         request.signal
       );
-      if (!res.ok) throw new Error(`Execute failed (${res.status}): ${await res.text()}`);
+      if (!res.ok) {
+        const { text, json } = await readErrorBody(res);
+        const detail = json ? json.message ?? text : text;
+        throw new ApiError(`Execute failed (${res.status}): ${detail}`, {
+          status: res.status,
+          code: reasonFrom(json, res.status)
+        });
+      }
       return res.json();
     },
     async options(workflow, payload) {
@@ -8965,13 +9148,19 @@ function prepareRequest(model, params2) {
   const payload = resolved.buildPayload(validatedCtx);
   return { ctx, workflow: resolved.workflow, payload, contract };
 }
-function parseResult(completed, model, contract) {
+function throwIfTerminalFailure(completed, model) {
   if (completed.status === "FAILED") {
-    throw new Error(`${model.name} failed: ${completed.error ?? "unknown error"}`);
+    throw new ApiError(`${model.name} failed: ${completed.error ?? "unknown error"}`, {
+      status: completed.statusCode ?? 502,
+      code: completed.reason ?? "generation_failed"
+    });
   }
   if (completed.status === "CANCELED") {
-    throw new Error(`${model.name} was canceled`);
+    throw new ApiError(`${model.name} was canceled`, { status: 499, code: "canceled" });
   }
+}
+function parseResult(completed, model, contract) {
+  throwIfTerminalFailure(completed, model);
   throwIfErrorResult(completed.result, model.name);
   const parsed = contract?.output ? contract.output.parse(completed.result) : completed.result;
   const multiItems = extractAllResults(parsed);
@@ -8984,22 +9173,23 @@ function parseResult(completed, model, contract) {
   }
   const url = extractUrl(parsed);
   if (!url) {
-    throw new Error(`${model.name}: unexpected response \u2014 no result URL`);
+    throw new ApiError(`${model.name}: unexpected response \u2014 no result URL`, {
+      status: 502,
+      code: "invalid_response"
+    });
   }
   return { url, results: [{ url }], model: model.id, handle: completed.handle, raw: parsed, usage: completed.usage };
 }
 function parseTextResult(completed, model) {
-  if (completed.status === "FAILED") {
-    throw new Error(`${model.name} failed: ${completed.error ?? "unknown error"}`);
-  }
-  if (completed.status === "CANCELED") {
-    throw new Error(`${model.name} was canceled`);
-  }
+  throwIfTerminalFailure(completed, model);
   throwIfErrorResult(completed.result, model.name);
   throwIfErrorResult(completed.raw, model.name);
   const text = extractText(completed.result) ?? extractText(completed.raw);
   if (text == null) {
-    throw new Error(`${model.name}: unexpected response \u2014 no text`);
+    throw new ApiError(`${model.name}: unexpected response \u2014 no text`, {
+      status: 502,
+      code: "invalid_response"
+    });
   }
   return { text, model: model.id, handle: completed.handle, raw: completed.raw ?? completed.result, usage: completed.usage };
 }
@@ -10134,7 +10324,10 @@ function createClient(config) {
     async generate(model, params2, options) {
       const resolved = resolveModel(model);
       if (resolved.mode === "text") {
-        throw new Error(`${resolved.name} is a text model \u2014 use generateText() instead.`);
+        throw new ApiError(`${resolved.name} is a text model \u2014 use generateText() instead.`, {
+          status: 400,
+          code: "wrong_model_mode"
+        });
       }
       const { workflow, payload, contract } = prepareRequest(resolved, params2);
       const drive = buildDrivePayloadOptions(resolved, params2, options);
@@ -10153,7 +10346,10 @@ function createClient(config) {
     async generateText(model, params2, options) {
       const resolved = resolveModel(model);
       if (resolved.mode !== "text") {
-        throw new Error(`${resolved.name} is not a text model \u2014 use generate() instead.`);
+        throw new ApiError(`${resolved.name} is not a text model \u2014 use generate() instead.`, {
+          status: 400,
+          code: "wrong_model_mode"
+        });
       }
       const { workflow, payload } = prepareRequest(resolved, params2);
       const completed = await executeModel(resolved, workflow, payload, options);
@@ -10227,10 +10423,16 @@ function createClient(config) {
         options
       );
       if (done.status === "FAILED" || done.status === "CANCELED") {
-        throw new Error(done.error ?? `${workflow} failed with status ${done.status}`);
+        throw new ApiError(done.error ?? `${workflow} failed with status ${done.status}`, {
+          status: done.statusCode ?? (done.status === "CANCELED" ? 499 : 502),
+          code: done.reason ?? (done.status === "CANCELED" ? "canceled" : "generation_failed")
+        });
       }
       if (done.result === void 0) {
-        throw new Error(`${workflow} completed but returned no result`);
+        throw new ApiError(`${workflow} completed but returned no result`, {
+          status: 502,
+          code: "invalid_response"
+        });
       }
       return done.result;
     },
@@ -10795,6 +10997,7 @@ var MinimaxH3 = "minimax-h3";
 var MinimaxH3Max = "minimax-h3-max";
 var MinimaxMusicV2 = "minimax-music-v2";
 var MinimaxMusicV3 = "minimax-music-v3";
+var MuseImage10 = "muse-image-1.0";
 var Ovi = "ovi";
 var PicsartChangeBg = "picsart-change-bg";
 var PicsartEnhance = "picsart-enhance";
@@ -11007,6 +11210,7 @@ var Models = {
   MinimaxH3Max,
   MinimaxMusicV2,
   MinimaxMusicV3,
+  MuseImage10,
   Ovi,
   PicsartChangeBg,
   PicsartEnhance,
@@ -11325,4 +11529,4 @@ function decodeDeepLinkPayload(encoded) {
   return deserializePayload(encoded);
 }
 
-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, toAvatarOption, toVoiceOption };
+export { ALL_MODELS, ApiError, 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, toAvatarOption, toVoiceOption };

package/package.json

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