@picsart/ai-sdk 5.24.1 → 5.26.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;
@@ -806,6 +810,18 @@ type ModelInputById = {
         seed?: number;
         enableSafetyChecker?: boolean;
     };
+    "minimax-h3-max-r2v": {
+        prompt: string;
+        imageUrls?: string[];
+        videoUrls?: string[];
+        audioUrls?: string[];
+        resolution?: "480p" | "768p";
+        duration?: number;
+        aspectRatio?: "adaptive" | "21:9" | "16:9" | "4:3" | "1:1" | "3:4" | "9:16";
+        promptExpansionMode?: "balanced" | "quality";
+        seed?: number;
+        enableSafetyChecker?: boolean;
+    };
     "minimax-music-v2": {
         prompt: string;
         lyricsPrompt?: string;
@@ -2641,6 +2657,7 @@ declare const Models: {
     readonly Minimax02Hd: "minimax-02-hd";
     readonly MinimaxH3: "minimax-h3";
     readonly MinimaxH3Max: "minimax-h3-max";
+    readonly MinimaxH3MaxR2v: "minimax-h3-max-r2v";
     readonly MinimaxMusicV2: "minimax-music-v2";
     readonly MinimaxMusicV3: "minimax-music-v3";
     readonly MuseImage10: "muse-image-1.0";
@@ -2774,6 +2791,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
@@ -2902,4 +2972,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 };
 }
@@ -6457,7 +6529,7 @@ var { MODELS: MODELS26 } = defineModels("minimax", [
     addedAt: "2026-08-28",
     workflow: "minimax/h3-max/text-to-video",
     editWorkflow: "minimax/h3-max/image-to-video",
-    estimatedTime: 180,
+    estimatedTime: 5,
     mode: "video",
     inputType: "t2v",
     description: "Top-tier MiniMax H3 Max video from text or a start/end frame, with prompt expansion. Up to 15s at 768p.",
@@ -6492,6 +6564,49 @@ var { MODELS: MODELS26 } = defineModels("minimax", [
         aspectRatio: { disabled: true, reason: "Aspect ratio follows the start frame image." }
       } }
     ]
+  },
+  {
+    // Reference-to-video sibling of minimax-h3-max (same fal.ai worker).
+    // The prompt addresses references by modality and order — Image 1,
+    // Video 1, Audio 1, … Reference clips are 2-15s each (≤15s combined per
+    // modality) and images + videos + audios must add up to ≤12 files —
+    // backend-enforced; paramConfig only carries the per-array maxima.
+    id: "minimax-h3-max-r2v",
+    name: "MiniMax H3 Max Ref-to-Video",
+    modelId: "fal-ai-h3-max",
+    addedAt: "2026-09-01",
+    workflow: "minimax/h3-max/reference-to-video",
+    estimatedTime: 5,
+    mode: "video",
+    inputType: "i2v",
+    description: "MiniMax H3 Max video from reference images, videos, and audio \u2014 refer to them in the prompt as Image 1, Video 1, Audio 1, in input order. Up to 15s at 768p.",
+    features: [
+      feat("Multi-Image Input", "input"),
+      feat("Video Input", "input"),
+      feat("Audio Input", "input"),
+      feat("768p", "resolution"),
+      feat("5-15 sec", "duration")
+    ],
+    paramConfig: {
+      ...params.prompt({ placeholder: "Image 1 is the protagonist. Keep her consistent with the reference while she walks through a sunlit garden..." }),
+      ...params.imageInput(9, "Reference Images"),
+      ...params.videoInputs(3, "Reference Videos"),
+      ...params.audioInputs(3, "Reference Audios"),
+      // Lowercase on purpose — same worker normalization as minimax-h3-max.
+      ...params.resolution(["480p", "768p"], "768p"),
+      ...params.durationRange(5, 15, 5),
+      ...params.aspectRatio(["adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"], "adaptive"),
+      // Unlike the T2V/I2V entry, this wire has no 'disabled' expansion mode.
+      ...p.enum("promptExpansionMode", ["balanced", "quality"], "balanced", { label: "Prompt Expansion" }),
+      // -1 (sentinel) means "pick a random seed"; the builder drops it.
+      ...p.range("seed", -1, 2147483647, -1),
+      ...p.boolean("enableSafetyChecker", true, "Safety Checker")
+    },
+    constraints: [
+      { when: { imageUrls: { exists: false }, videoUrls: { exists: false } }, then: {
+        audioUrls: { disabled: true, reason: "Audio cannot be the only reference \u2014 add an image or video." }
+      } }
+    ]
   }
 ]);
 
@@ -6523,9 +6638,23 @@ var buildMinimaxH3MaxPayload = (input) => ({
   ...input.seed != null && input.seed !== -1 ? { seed: input.seed } : {},
   enable_safety_checker: input.enableSafetyChecker ?? true
 });
+var buildMinimaxH3MaxR2VPayload = (input) => ({
+  prompt: input.prompt,
+  prompt_expansion_mode: input.promptExpansionMode ?? "balanced",
+  duration: input.duration ?? 5,
+  resolution: input.resolution ?? "768p",
+  aspect_ratio: input.aspectRatio ?? "adaptive",
+  ...input.imageUrls?.length ? { reference_image_urls: input.imageUrls } : {},
+  ...input.videoUrls?.length ? { reference_video_urls: input.videoUrls } : {},
+  ...input.audioUrls?.length ? { reference_audio_urls: input.audioUrls } : {},
+  // -1 is the paramConfig sentinel for "random seed" — omit it on the wire.
+  ...input.seed != null && input.seed !== -1 ? { seed: input.seed } : {},
+  enable_safety_checker: input.enableSafetyChecker ?? true
+});
 registerPayloads(MODELS26, {
   "minimax-music-v3": buildMinimaxMusicV3Payload,
-  "minimax-h3-max": buildMinimaxH3MaxPayload
+  "minimax-h3-max": buildMinimaxH3MaxPayload,
+  "minimax-h3-max-r2v": buildMinimaxH3MaxR2VPayload
 });
 registerEditPayloads(MODELS26, {
   "minimax-h3-max": buildMinimaxH3MaxPayload
@@ -8676,14 +8805,22 @@ var getModelsByMode = (mode, includeDisabled = false) => ALL_MODELS.filter((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;
     }
   };
@@ -8692,7 +8829,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;
     }
@@ -8735,7 +8875,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) {
@@ -8937,7 +9082,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;
 }
 
@@ -8977,18 +9124,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) {
@@ -8997,7 +9160,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) {
@@ -9035,13 +9205,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);
@@ -9054,22 +9230,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 };
 }
@@ -10204,7 +10381,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);
@@ -10223,7 +10403,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);
@@ -10297,10 +10480,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;
     },
@@ -10863,6 +11052,7 @@ var Lyria3Pro = "lyria-3-pro";
 var Minimax02Hd = "minimax-02-hd";
 var MinimaxH3 = "minimax-h3";
 var MinimaxH3Max = "minimax-h3-max";
+var MinimaxH3MaxR2v = "minimax-h3-max-r2v";
 var MinimaxMusicV2 = "minimax-music-v2";
 var MinimaxMusicV3 = "minimax-music-v3";
 var MuseImage10 = "muse-image-1.0";
@@ -11076,6 +11266,7 @@ var Models = {
   Minimax02Hd,
   MinimaxH3,
   MinimaxH3Max,
+  MinimaxH3MaxR2v,
   MinimaxMusicV2,
   MinimaxMusicV3,
   MuseImage10,
@@ -11397,4 +11588,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.1",
+  "version": "5.26.0",
   "type": "module",
   "description": "Type-safe SDK for 100+ AI models — image, video, audio, and text generation with Picsart",
   "license": "MIT",