@picsart/ai-sdk 6.24.1 → 6.28.0

package/index.d.ts

@@ -759,6 +759,18 @@ type ModelInputById = {
         voiceId: string;
         prompt: string;
     };
+    "heygen-video-1": {
+        prompt: string;
+        startFrame?: 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";
+        promptEnhancement?: "turbo" | "quality" | "disabled";
+        seed?: number;
+    };
     "heygen-video-avatar": {
         videoId: string;
         engine?: "avatar_iv" | "avatar_v";
@@ -1898,6 +1910,13 @@ type ModelInputById = {
         videoUrl: string;
         model?: "Proteus" | "Artemis HQ" | "Artemis MQ" | "Artemis LQ" | "Nyx" | "Nyx Fast" | "Nyx XL" | "Nyx HF" | "Gaia HQ" | "Gaia CG" | "Gaia 2" | "Starlight Precise 2.5" | "Starlight HQ" | "Starlight Mini" | "Starlight Sharp" | "Starlight Fast 2";
     };
+    "typesafe-evaluate": {
+        state: string;
+        questions: Record<string, {
+            type: "noul" | "choice" | "score";
+            instructions: unknown;
+        } & Record<string, unknown>>;
+    };
     "veed-fabric-v1": {
         prompt?: string;
         resolution?: "480p" | "720p";
@@ -2037,6 +2056,8 @@ type ModelInput<M extends TypedModelId> = ModelInputById[M];
 /** IDs of text-generation (LLM) models — narrows generateText(). */
 type TextModelId = "claude-fable-5" | "claude-fable-5-1" | "claude-haiku-4-5" | "claude-opus-4-8" | "claude-opus-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-5" | "eleven-speech-to-text" | "gemini-2.5-flash" | "gemini-3-pro" | "gemini-3.5-flash-lite" | "gemini-3.6-flash" | "gemini-3.7-flash" | "gemini-3.8-flash" | "gpt-4.1-mini" | "gpt-4.1-nano" | "gpt-4o" | "gpt-4o-mini" | "gpt-5" | "gpt-5-mini" | "gpt-5.1" | "gpt-5.2" | "gpt-5.5" | "gpt-5.6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-6-astra" | "gpt-6-luna" | "gpt-6-sol";
 type TextModelInputById = Pick<ModelInputById, TextModelId>;
+/** IDs of structured-output (json-mode) models — narrows run()'s result type. */
+type JsonModelId = "typesafe-evaluate";
 
 interface ParamSchema {
     type: 'string' | 'number' | 'boolean' | 'file';
@@ -2248,18 +2269,34 @@ interface FileDescriptor {
      */
     maxBytes?: number;
 }
+/** Any value — no validation, generates as `unknown`. Only meaningful as an
+ *  ObjectDescriptor's `additionalProperties` (or a nested field): it marks a
+ *  pass-through slot whose shape the vendor owns. */
+interface UnknownDescriptor {
+    kind: 'unknown';
+}
 interface ObjectDescriptor {
     kind: 'object';
-    /** Nested fields use the flat EntryMeta + Descriptor merge — same shape as
+    /** Declared fields — flat EntryMeta + Descriptor merge, same shape as
      *  EnumEntry / RangeEntry / etc. Authors can mark a nested field optional
      *  by setting `required: false`. Default is required. */
-    fields: Record<string, EntryMeta & ParamDescriptor>;
+    fields?: Record<string, EntryMeta & ParamDescriptor>;
+    /**
+     * JSON-Schema-style `additionalProperties`: keys beyond `fields` are
+     * allowed, each value validated against this descriptor. With no `fields`
+     * the object is an open-keyed dictionary (generates `Record<string, V>` —
+     * e.g. question id → question object); alongside `fields` it admits
+     * vendor-defined extras (generates `{ …fields } & Record<string, V>`).
+     * Use `{ kind: 'unknown' }` to pass extras through unvalidated.
+     * Omitted → closed shape: exactly `fields`.
+     */
+    additionalProperties?: ParamDescriptor;
     array?: {
         min?: number;
         max?: number;
     };
 }
-type ParamDescriptor = EnumDescriptor<string> | EnumDescriptor<number> | CatalogDescriptor | RangeDescriptor | BooleanDescriptor | TextDescriptor | FileDescriptor | ObjectDescriptor;
+type ParamDescriptor = EnumDescriptor<string> | EnumDescriptor<number> | CatalogDescriptor | RangeDescriptor | BooleanDescriptor | TextDescriptor | FileDescriptor | ObjectDescriptor | UnknownDescriptor;
 interface ParamEntry {
     label?: string;
     required?: boolean;
@@ -2294,6 +2331,7 @@ type BooleanEntry = EntryMeta & BooleanDescriptor;
 type TextEntry = EntryMeta & TextDescriptor;
 type FileEntry = EntryMeta & FileDescriptor;
 type ObjectEntry = EntryMeta & ObjectDescriptor;
+type UnknownEntry = EntryMeta & UnknownDescriptor;
 /** Flat param entry with key — returned by ModelAccessor.params(). */
 type FlatParamEntry = EntryMeta & ParamDescriptor & {
     key: string;
@@ -2421,11 +2459,13 @@ interface ModelFilter {
     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' | 'meta';
+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' | 'typesafe';
 /** Provider used by model definitions. */
 type Provider = AppProvider;
-/** App generation modes. */
-type GenerationMode = 'video' | 'image' | 'audio' | 'text';
+/** App generation modes. `json` marks structured-output models (judges,
+ *  evaluators, classifiers) — no media URL, no extractable text; their parsed
+ *  result is returned as-is by `ai.run()`. */
+type GenerationMode = 'video' | 'image' | 'audio' | 'text' | 'json';
 /** App input types. */
 type InputType = 't2v' | 'i2v' | 'v2v' | 'a2v' | 't2i' | 'i2i' | 't2a' | 'v2a' | 'tts' | 'sts' | 'sfx' | 'music' | 't2t' | 'i2t' | 'v2t' | 'a2t';
 interface ModelFeature {
@@ -3109,6 +3149,20 @@ interface GenerateResult {
     /** Present when Drive is enabled and the file was saved. */
     drive?: DriveSaveResult;
 }
+/**
+ * Response of {@link AiClient.run} — the same shape `ai.apis.run()` answers
+ * ({ result, status, usage, id }), in the SDK's own vocabulary.
+ */
+interface RunResponse<R = unknown> {
+    /** The task result as-is, validated by the model's `outputSchema` when declared. */
+    result: R;
+    /** Always `COMPLETED` — failures throw {@link ApiError} instead. */
+    status: 'COMPLETED';
+    /** Credit usage reported by the platform — same structure as the pluggable APIs' GenAITaskResponse. */
+    usage?: CreditUsage;
+    /** The generation/job id — absent for syncExecute models (nothing to poll). */
+    id?: string;
+}
 /** Result of a text-generation (LLM) model. */
 interface GenerateTextResult {
     /** Generated text. */
@@ -3177,13 +3231,13 @@ interface GenerateOptions {
     signal?: AbortSignal;
     /**
      * Poll interval for the async status loop, in ms. Overrides the model's
-     * `pollOptions` and the mode default (video 2s; image/audio/text 1s).
+     * `pollOptions` and the mode default (video 2s; image/audio/text/json 1s).
      */
     intervalMs?: number;
     /**
      * Max poll attempts before the call throws a timeout. Overrides the model's
      * `pollOptions` and the mode default (video 1800 ≈ 1 hour;
-     * image/audio/text 1200 ≈ 20 min).
+     * image/audio/text/json 1200 ≈ 20 min).
      */
     maxAttempts?: number;
     /** Save to a specific subfolder instead of the root (legacy — used by SDK DriveConfig). */
@@ -3201,9 +3255,19 @@ interface GenerateOptions {
     app?: AppIdentity;
 }
 /** Non-text (image/video/audio) model IDs — the media generation surface. */
-type MediaModelId = Exclude<TypedModelId, TextModelId>;
+type MediaModelId = Exclude<TypedModelId, TextModelId | JsonModelId>;
 /** AI SDK client with type-safe, model-aware method signatures. */
 interface AiClient {
+    /**
+     * Run any model by id and get the task result back, generically — the
+     * model-id counterpart of {@link ApisClient.run}. Works on every model:
+     * builds and validates the payload from paramConfig, executes the workflow,
+     * applies the model's `outputSchema` when declared, and answers the task
+     * result as-is (no media-URL/text extraction, no Drive save). The only
+     * generation surface for json-mode (structured-output) models. Type the
+     * result via `R` (mirrors `ai.apis.run()`): `ai.run<MyResult>(id, params)`.
+     */
+    run<R = unknown, M extends TypedModelId = TypedModelId>(model: M, params: ModelInputById[M], options?: GenerateOptions): Promise<RunResponse<R>>;
     /** Generate content using a media model. Text/LLM models use generateText(). */
     generate<M extends MediaModelId>(model: M, params: ModelInputById[M], options?: GenerateOptions): Promise<GenerateResult>;
     /** Generate text using an LLM model. Returns the generated text plus the raw response. */
@@ -3361,6 +3425,7 @@ declare const Models: {
     readonly Happyhorse11R2v: "happyhorse-1.1-r2v";
     readonly Happyhorse11T2v: "happyhorse-1.1-t2v";
     readonly HeygenTalkingPhoto: "heygen-talking-photo";
+    readonly HeygenVideo1: "heygen-video-1";
     readonly HeygenVideoAvatar: "heygen-video-avatar";
     readonly HunyuanV3: "hunyuan-v3";
     readonly Ideogram45: "ideogram-4-5";
@@ -3505,6 +3570,7 @@ declare const Models: {
     readonly SpicyMayo: "spicy-mayo";
     readonly TopazUpscaleImage: "topaz-upscale-image";
     readonly TopazUpscaleVideo: "topaz-upscale-video";
+    readonly TypesafeEvaluate: "typesafe-evaluate";
     readonly VeedFabricV1: "veed-fabric-v1";
     readonly VeedFabricV1Fast: "veed-fabric-v1-fast";
     readonly Veo31: "veo-3.1";
@@ -3661,4 +3727,4 @@ declare const getModel: (id: string) => ModelDefinition | undefined;
  */
 declare const findModel: (ref: string) => ModelDefinition | undefined;
 
-export { ALL_MODELS, type AiClient, ApiError, type ApiErrorCode, type ApiErrorInit, type ApiResponse, type ApiRunOptions, type ApiSchemas, type ApisClient, type AppIdentity, type AppType, type AuthenticatedFetch, type AvatarOption, type BooleanDescriptor, type BooleanEntry, type CatalogDescriptor, type CatalogEntry, type CatalogItem, type CatalogPage, type CatalogPageOptions, type CatalogPreview, type CatalogQuery, type CatalogResult, type CatalogSource, type CatalogsClient, type CatalogsOptions, type ClientConfig, type CreditRange, type CreditRangeContext, type CreditTier, type CreditUsage, DEFAULT_VISIBLE_RELEASES, type DeepLinkResult, type DriveAttributes, type DriveClient, type DriveConfig, type DriveDraftInfo, type DriveFile, type DriveFileDetails, type DriveFolder, type DriveMediaItem, type DriveSaveResult, type EntryMeta, type EnumDescriptor, type EnumEntry, type EnumOption, type FileDescriptor, type FileEntry, type FlatParamEntry, type GenerateOptions, type GenerateResult, type GenerateResultItem, type GenerateResultItemMetadata, type GenerateTextResult, type GenerationContext, type GenerationEvent, GenerationEventType, type GenerationFile, type GenerationMode, type GenerationOptions, type GenerationProgress, type GenerationProvenance, type ListOptions, type MediaModelId, type MediaTypeFilter, Model, type ModelDefinition, type ModelDescriptor, type ModelFilter, type ModelInput, type ModelInputById, type ModelMeta, type ModelParams, type ModelParamsAccessor, Models, type ObjectDescriptor, type ObjectEntry, type OptionsResult, type ParamDescriptor, type ParamEntry, type ParamOption, type PayloadDriveFolderOptions, type PayloadDriveOptions, type PayloadInputsTransformationOptions, type PricingOptions, type ProviderInfo, type RangeDescriptor, type RangeEntry, type ReleaseTag, type SaveParams, type SdkPayload, type SdkTransport, type SeedanceDraftTask, type TextDescriptor, type TextEntry, type TextModelId, type TextModelInputById, type ToolUsage, type TransportPollOptions, type TransportResult, type TypedModelId, type UserReaction, type ValidationResult, type VoiceOption, type WorkflowJobHandle, type WorkflowSubmitRequest, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, expectedOutputFormat, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, isVisibleForReleases, parseGeneration, releaseOf, resolveExtension, toAvatarOption, toVoiceOption };
+export { ALL_MODELS, type AiClient, ApiError, type ApiErrorCode, type ApiErrorInit, type ApiResponse, type ApiRunOptions, type ApiSchemas, type ApisClient, type AppIdentity, type AppType, type AuthenticatedFetch, type AvatarOption, type BooleanDescriptor, type BooleanEntry, type CatalogDescriptor, type CatalogEntry, type CatalogItem, type CatalogPage, type CatalogPageOptions, type CatalogPreview, type CatalogQuery, type CatalogResult, type CatalogSource, type CatalogsClient, type CatalogsOptions, type ClientConfig, type CreditRange, type CreditRangeContext, type CreditTier, type CreditUsage, DEFAULT_VISIBLE_RELEASES, type DeepLinkResult, type DriveAttributes, type DriveClient, type DriveConfig, type DriveDraftInfo, type DriveFile, type DriveFileDetails, type DriveFolder, type DriveMediaItem, type DriveSaveResult, type EntryMeta, type EnumDescriptor, type EnumEntry, type EnumOption, type FileDescriptor, type FileEntry, type FlatParamEntry, type GenerateOptions, type GenerateResult, type GenerateResultItem, type GenerateResultItemMetadata, type GenerateTextResult, type GenerationContext, type GenerationEvent, GenerationEventType, type GenerationFile, type GenerationMode, type GenerationOptions, type GenerationProgress, type GenerationProvenance, type JsonModelId, type ListOptions, type MediaModelId, type MediaTypeFilter, Model, type ModelDefinition, type ModelDescriptor, type ModelFilter, type ModelInput, type ModelInputById, type ModelMeta, type ModelParams, type ModelParamsAccessor, Models, type ObjectDescriptor, type ObjectEntry, type OptionsResult, type ParamDescriptor, type ParamEntry, type ParamOption, type PayloadDriveFolderOptions, type PayloadDriveOptions, type PayloadInputsTransformationOptions, type PricingOptions, type ProviderInfo, type RangeDescriptor, type RangeEntry, type ReleaseTag, type RunResponse, type SaveParams, type SdkPayload, type SdkTransport, type SeedanceDraftTask, type TextDescriptor, type TextEntry, type TextModelId, type TextModelInputById, type ToolUsage, type TransportPollOptions, type TransportResult, type TypedModelId, type UnknownDescriptor, type UnknownEntry, type UserReaction, type ValidationResult, type VoiceOption, type WorkflowJobHandle, type WorkflowSubmitRequest, buildFilename, buildGenerationAttributes, catalog, createClient, decodeDeepLinkPayload, encodeDeepLinkPayload, expectedOutputFormat, findModel, getModel, getModelsByMode, getVoiceById, inferResourceType, isVisibleForReleases, parseGeneration, releaseOf, resolveExtension, toAvatarOption, toVoiceOption };

package/index.js

@@ -566,12 +566,22 @@ function validateDescriptor(key, d, val, required) {
           `"${key}" allows at most ${d.array.max} items`
         );
       }
+      const declared = d.fields ?? {};
       for (const item of items) {
         if (item == null || typeof item !== "object" || Array.isArray(item)) {
-          throw new Error(`"${key}" items must be objects`);
+          throw new Error(d.array ? `"${key}" items must be objects` : `"${key}" must be an object`);
         }
-        for (const [fk, fd] of Object.entries(d.fields)) {
-          validateDescriptor(`${key}.${fk}`, fd, item[fk]);
+        if (required && !d.array && d.additionalProperties && Object.keys(declared).length === 0 && Object.keys(item).length === 0) {
+          throw new Error(`"${key}" is required`);
+        }
+        for (const [fk, fd] of Object.entries(declared)) {
+          validateDescriptor(`${key}.${fk}`, fd, item[fk], fd.required);
+        }
+        if (d.additionalProperties) {
+          for (const [ek, ev] of Object.entries(item)) {
+            if (ek in declared) continue;
+            validateDescriptor(`${key}.${ek}`, d.additionalProperties, ev, true);
+          }
         }
       }
       break;
@@ -784,7 +794,8 @@ var providers = {
   anthropic: { color: "#D97757", label: "CL", name: "Anthropic" },
   async: { color: "#5E5CE6", label: "AA", name: "Async AI" },
   captionsai: { color: "#1D1F20", label: "MR", name: "Mirage" },
-  meta: { color: "#0081FB", label: "MT", name: "Meta" }
+  meta: { color: "#0081FB", label: "MT", name: "Meta" },
+  typesafe: { color: "#3E6B8F", label: "TS", name: "TypeSafe" }
 };
 
 // src/core/descriptors/presets.ts
@@ -1162,7 +1173,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);
@@ -1198,19 +1209,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;
   }
 }
@@ -4176,6 +4187,10 @@ var SEEDANCE_25_VIDEO_BOUNDS = {
   maxDurationSec: SEEDANCE_25_MAX_MEDIA_SEC,
   maxFrameRate: SEEDANCE_MAX_FRAME_RATE
 };
+var SEEDANCE_25_EDIT_SOURCE_BOUNDS = {
+  ...SEEDANCE_25_VIDEO_BOUNDS,
+  minDurationSec: 4
+};
 var SEEDANCE_20_VIDEO_BOUNDS = {
   minAspectRatio: SEEDANCE_MIN_ASPECT_RATIO,
   maxAspectRatio: SEEDANCE_MAX_ASPECT_RATIO,
@@ -4658,7 +4673,7 @@ var { MODELS: MODELS13 } = defineModels("bytedance", [
       ...seedance25DraftParam,
       // Every limit rides in `bounds`; the positional maxDuration / maxShortSide
       // / maxBytes args predate it and are skipped rather than duplicated.
-      ...params.videoInput("Source Video", "reference", true, void 0, void 0, void 0, SEEDANCE_25_VIDEO_BOUNDS),
+      ...params.videoInput("Source Video", "reference", true, void 0, void 0, void 0, SEEDANCE_25_EDIT_SOURCE_BOUNDS),
       ...params.imageInput(30, "Reference Images", false, "reference", SEEDANCE_IMAGE_BOUNDS)
     }
   },
@@ -4690,7 +4705,7 @@ var { MODELS: MODELS13 } = defineModels("bytedance", [
       ...seedance25DraftParam,
       // Every limit rides in `bounds`; the positional maxDuration / maxShortSide
       // / maxBytes args predate it and are skipped rather than duplicated.
-      ...params.videoInput("Source Video", "reference", true, void 0, void 0, void 0, SEEDANCE_25_VIDEO_BOUNDS),
+      ...params.videoInput("Source Video", "reference", true, void 0, void 0, void 0, SEEDANCE_25_EDIT_SOURCE_BOUNDS),
       ...params.imageInput(30, "Reference Images", false, "reference", SEEDANCE_IMAGE_BOUNDS)
     }
   },
@@ -7674,7 +7689,7 @@ var buildElevenLabsDialoguePayload = (catalogId, modelId) => (input) => {
 };
 function dialogueCharacterCap(catalogId) {
   const descriptor = MODELS24.find((m) => m.id === catalogId)?.paramConfig.dialogue?.descriptor;
-  const text = descriptor?.kind === "object" ? descriptor.fields.text : void 0;
+  const text = descriptor?.kind === "object" ? descriptor.fields?.text : void 0;
   const cap = text && "maxLength" in text ? text.maxLength : void 0;
   if (typeof cap !== "number") {
     throw new Error(`${catalogId}: dialogue entry declares no per-line maxLength to derive the cap from`);
@@ -7750,6 +7765,32 @@ var dynamicVoiceConfig = {
     catalog: { workflow: "heygen/v1/catalog/voices" }
   })
 };
+var VIDEO1_MODE_EXCLUSIVE = "A first frame and references cannot be combined \u2014 each picks a different mode.";
+var VIDEO1_RATIO_FOLLOWS_FRAME = "Aspect ratio follows the first-frame image.";
+var VIDEO1_ADAPTIVE_NEEDS_REFS = "Adaptive aspect ratio follows the references \u2014 add one to use it.";
+var VIDEO1_RATIOS = ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"];
+var heygenVideo1Constraints = [
+  { when: { startFrame: { exists: true } }, then: {
+    imageUrls: { disabled: true, reason: VIDEO1_MODE_EXCLUSIVE },
+    videoUrls: { disabled: true, reason: VIDEO1_MODE_EXCLUSIVE },
+    audioUrls: { disabled: true, reason: VIDEO1_MODE_EXCLUSIVE },
+    // image_to_video always follows the first frame — the ratio is not a choice.
+    aspectRatio: { disabled: true, reason: VIDEO1_RATIO_FOLLOWS_FRAME }
+  } },
+  { when: { imageUrls: { exists: true } }, then: {
+    startFrame: { disabled: true, reason: VIDEO1_MODE_EXCLUSIVE }
+  } },
+  { when: { videoUrls: { exists: true } }, then: {
+    startFrame: { disabled: true, reason: VIDEO1_MODE_EXCLUSIVE }
+  } },
+  { when: { audioUrls: { exists: true } }, then: {
+    startFrame: { disabled: true, reason: VIDEO1_MODE_EXCLUSIVE }
+  } },
+  // 'adaptive' means "follow the first reference" — no meaning without one.
+  { when: { imageUrls: { exists: false }, videoUrls: { exists: false }, audioUrls: { exists: false } }, then: {
+    aspectRatio: { allowed: [...VIDEO1_RATIOS], reason: VIDEO1_ADAPTIVE_NEEDS_REFS }
+  } }
+];
 var { MODELS: MODELS25 } = defineModels("heygen", [
   // ── Photo Avatar (i2v) ────────────────────────────────────────────
   {
@@ -7804,9 +7845,73 @@ var { MODELS: MODELS25 } = defineModels("heygen", [
       ...dynamicVoiceConfig,
       ...params.prompt({ minLength: 20, maxLength: 5e3, placeholder: "Write the script your avatar will speak (at least 20 characters)..." })
     }
+  },
+  // ── HeyGen Video (t2v / i2v / r2v) ────────────────────────────────
+  {
+    // One entry for all three modes: the inputs pick it — a first-frame image
+    // animates that image, references generate from references, a bare prompt
+    // generates from text. Payload assembly lives in heygen.payloads.ts.
+    id: "heygen-video-1",
+    name: "HeyGen Video",
+    addedAt: "2026-10-05",
+    workflow: "heygen/v1/models/video/generate",
+    estimatedTime: 60,
+    mode: "video",
+    inputType: "t2v",
+    description: "HeyGen Video \u2014 video with native audio from text, a first-frame image, or up to 12 reference images, videos and audio. Refer to references in the prompt as Picture 1, Video 1, in input order. Up to 15s at 768p.",
+    features: [
+      feat("Start Frame", "frame"),
+      feat("Multi-Image Input", "input"),
+      feat("Video Input", "input"),
+      feat("Audio Input", "input"),
+      feat("Audio", "audio"),
+      feat("5-15 sec", "duration")
+    ],
+    paramConfig: {
+      ...params.prompt({ maxLength: 32e3 }),
+      ...params.startFrame("Start Frame", false),
+      // Reference slots, reference-to-video route. The ≤12 files combined
+      // across images + videos + audios stay backend-enforced.
+      ...params.imageInput(9, "Reference Images", false, "reference"),
+      ...params.videoInputs(3, "Reference Videos"),
+      ...params.audioInputs(3, "Reference Audios"),
+      ...params.resolution(["480p", "768p"], "768p"),
+      ...params.durationRange(5, 15, 5),
+      // 'adaptive' means "follow the references" — constrained below.
+      ...params.aspectRatio(["adaptive", "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"], "16:9"),
+      ...p.enum("promptEnhancement", ["turbo", "quality", "disabled"], "turbo", { label: "Prompt Enhancement" }),
+      // Unsigned 32-bit per the schema; sent only when the user sets it.
+      ...params.seed(4294967295)
+    },
+    constraints: heygenVideo1Constraints
   }
 ]);
 
+// src/vendors/catalog/heygen.payloads.ts
+var asMediaRef = (url) => ({ type: "url", url });
+var buildHeygenVideo1Payload = (input) => {
+  const hasFrame = !!input.startFrame;
+  const hasReferences = !!(input.imageUrls?.length || input.videoUrls?.length || input.audioUrls?.length);
+  return {
+    model: "heygen-video-1",
+    prompt: input.prompt,
+    duration: input.duration ?? 5,
+    resolution: input.resolution ?? "768p",
+    prompt_enhancement: input.promptEnhancement ?? "turbo",
+    // With references the default is 'adaptive' (follow the first one); from
+    // the prompt alone it is 16:9.
+    ...hasFrame ? {} : { aspect_ratio: input.aspectRatio ?? (hasReferences ? "adaptive" : "16:9") },
+    ...input.startFrame ? { image: asMediaRef(input.startFrame) } : {},
+    ...input.imageUrls?.length ? { reference_images: input.imageUrls.map(asMediaRef) } : {},
+    ...input.videoUrls?.length ? { reference_videos: input.videoUrls.map(asMediaRef) } : {},
+    ...input.audioUrls?.length ? { reference_audio: input.audioUrls.map(asMediaRef) } : {},
+    ...input.seed != null ? { seed: input.seed } : {}
+  };
+};
+registerPayloads(MODELS25, {
+  "heygen-video-1": buildHeygenVideo1Payload
+});
+
 // src/vendors/catalog/minimax.payloads.ts
 var buildMinimaxMusicV3Payload = (input) => ({
   prompt: input.prompt,
@@ -10562,6 +10667,77 @@ registerEditPayloads(MODELS37, {
   "muse-image-1.0": buildMuseImageEditPayload
 });
 
+// src/vendors/catalog/typesafe.ts
+var evaluateOutputSchema = {
+  parse(output) {
+    const obj = output;
+    if (!obj || typeof obj.answers !== "object" || obj.answers == null) {
+      throw new Error("No answers in TypeSafe evaluate response");
+    }
+    return output;
+  }
+};
+var { MODELS: MODELS38 } = defineModels("typesafe", [
+  {
+    id: "typesafe-evaluate",
+    name: "Jev",
+    workflow: "typesafe/v1/systemone/evaluate",
+    addedAt: "2026-10-05",
+    modelId: "jev-latest",
+    estimatedTime: 6,
+    badge: ["new"],
+    mode: "json",
+    inputType: "t2t",
+    outputSchema: evaluateOutputSchema,
+    description: "Evaluate content against named questions (yes/no, choice, score) and get structured answers back.",
+    features: [feat("Structured Output", "characteristic")],
+    paramConfig: {
+      ...p.text("state", { label: "Content", required: true }),
+      questions: {
+        label: "Questions",
+        required: true,
+        // Dictionary of caller-chosen question ids → question objects.
+        descriptor: {
+          kind: "object",
+          additionalProperties: {
+            kind: "object",
+            fields: {
+              type: {
+                kind: "enum",
+                valueType: "string",
+                default: "noul",
+                required: true,
+                options: [
+                  { id: "noul", label: "Yes/No" },
+                  { id: "choice", label: "Choice" },
+                  { id: "score", label: "Score" }
+                ]
+              },
+              // Plain string or a structured instruction object — the shape is
+              // vendor-defined (see https://docs.typesafe.ai/api), so only
+              // presence is enforced here.
+              instructions: { kind: "unknown", required: true }
+            },
+            // Choice options, score bounds, etc. are question-type-specific —
+            // see https://docs.typesafe.ai/api; pass them through unvalidated.
+            additionalProperties: { kind: "unknown" }
+          }
+        }
+      }
+    }
+  }
+]);
+
+// src/vendors/catalog/typesafe.payloads.ts
+var buildEvaluatePayload = (input) => ({
+  state: input.state,
+  model: "jev-latest",
+  questions: input.questions
+});
+registerPayloads(MODELS38, {
+  "typesafe-evaluate": buildEvaluatePayload
+});
+
 // src/vendors/catalog/creatify.payloads.ts
 var buildCreatifyBorealPayload = (input) => ({
   prompt: input.prompt,
@@ -10716,7 +10892,8 @@ var ALL_MODELS = [
   ...MODELS34,
   ...MODELS35,
   ...MODELS36,
-  ...MODELS37
+  ...MODELS37,
+  ...MODELS38
 ];
 var getModelsByMode = (mode, includeHidden = false) => ALL_MODELS.filter((m) => m.mode === mode && (includeHidden || isVisibleForReleases(m)));
 
@@ -12262,6 +12439,24 @@ function parseTextResult(completed, model) {
   }
   return { text, model: model.id, raw: completed.raw ?? completed.result, usage: completed.usage };
 }
+function parseRunResult(completed, model, contract) {
+  throwIfErrorResult(completed.result, model.name);
+  throwIfErrorResult(completed.raw, model.name);
+  const result = contract?.output ? contract.output.parse(completed.result) : completed.result;
+  if (result == null) {
+    throw new ApiError(`${model.name}: unexpected response \u2014 empty result`, {
+      status: 502,
+      code: "invalid_response"
+    });
+  }
+  return {
+    result,
+    status: "COMPLETED",
+    usage: completed.usage,
+    // Sync executions have no job id (nothing to poll) — omit rather than ''.
+    ...completed.handle.id ? { id: completed.handle.id } : {}
+  };
+}
 
 // src/core/limits.ts
 var MAX_DRIVE_PROMPT_LENGTH = 18e3;
@@ -13038,6 +13233,7 @@ var GenerationEventType = {
 };
 
 // src/client/index.ts
+var MEDIA_MODES = /* @__PURE__ */ new Set(["video", "image", "audio"]);
 var MODE_POLL_DEFAULTS = {
   video: { intervalMs: 2e3, maxAttempts: 1800 },
   // 2s × 1800 = 1 hour
@@ -13045,7 +13241,9 @@ var MODE_POLL_DEFAULTS = {
   // 1s × 1200 = 20 min
   audio: { intervalMs: 1e3, maxAttempts: 1200 },
   // 1s × 1200 = 20 min
-  text: { intervalMs: 1e3, maxAttempts: 1200 }
+  text: { intervalMs: 1e3, maxAttempts: 1200 },
+  // 1s × 1200 = 20 min
+  json: { intervalMs: 1e3, maxAttempts: 1200 }
   // 1s × 1200 = 20 min
 };
 function resolvePollOptions(model, overrides) {
@@ -13103,13 +13301,16 @@ function createClient(config) {
     if (!transport.submit) throw unsupportedTransport("submit");
     if (!transport.poll) throw unsupportedTransport("polling");
   }
+  function isMediaModel(model) {
+    return MEDIA_MODES.has(model.mode);
+  }
   function assertMediaModel(model) {
-    if (model.mode === "text") {
-      throw new ApiError(`${model.name} is a text model \u2014 use generateText() instead.`, {
-        status: 400,
-        code: "wrong_model_mode"
-      });
-    }
+    if (isMediaModel(model)) return;
+    const alternative = model.mode === "text" ? "generateText()" : "run()";
+    throw new ApiError(`${model.name} is a ${model.mode} model \u2014 use ${alternative} instead.`, {
+      status: 400,
+      code: "wrong_model_mode"
+    });
   }
   async function submitJob(workflow, payload, signal) {
     if (signal?.aborted) {
@@ -13192,6 +13393,21 @@ function createClient(config) {
   }
   return {
     // ── Simple path ──────────────────────────────────────────────────
+    /**
+     * Run any model by id and get the task result back, generically — the
+     * model-id counterpart of `ai.apis.run()`. Works on every model: builds
+     * and validates the payload from paramConfig, executes the workflow
+     * (sync or async), applies the model's `outputSchema` when declared, and
+     * returns the task result as-is — no media-URL or text extraction, no
+     * Drive save, no options injection. The only generation surface for
+     * json-mode (structured-output) models.
+     */
+    async run(model, params2, options) {
+      const resolved = resolveModel(model);
+      const { workflow, payload, contract } = prepareRequest(resolved, params2);
+      const completed = await executeModel(resolved, workflow, payload, options);
+      return parseRunResult(completed, resolved, contract);
+    },
     /**
      * Generate content using a model.
      *
@@ -13470,6 +13686,7 @@ var Happyhorse10VideoEdit = "happyhorse-1.0-video-edit";
 var Happyhorse11R2v = "happyhorse-1.1-r2v";
 var Happyhorse11T2v = "happyhorse-1.1-t2v";
 var HeygenTalkingPhoto = "heygen-talking-photo";
+var HeygenVideo1 = "heygen-video-1";
 var HeygenVideoAvatar = "heygen-video-avatar";
 var HunyuanV3 = "hunyuan-v3";
 var Ideogram45 = "ideogram-4-5";
@@ -13614,6 +13831,7 @@ var Seedream50Pro = "seedream-5.0-pro";
 var SpicyMayo = "spicy-mayo";
 var TopazUpscaleImage = "topaz-upscale-image";
 var TopazUpscaleVideo = "topaz-upscale-video";
+var TypesafeEvaluate = "typesafe-evaluate";
 var VeedFabricV1 = "veed-fabric-v1";
 var VeedFabricV1Fast = "veed-fabric-v1-fast";
 var Veo31 = "veo-3.1";
@@ -13725,6 +13943,7 @@ var Models = {
   Happyhorse11R2v,
   Happyhorse11T2v,
   HeygenTalkingPhoto,
+  HeygenVideo1,
   HeygenVideoAvatar,
   HunyuanV3,
   Ideogram45,
@@ -13869,6 +14088,7 @@ var Models = {
   SpicyMayo,
   TopazUpscaleImage,
   TopazUpscaleVideo,
+  TypesafeEvaluate,
   VeedFabricV1,
   VeedFabricV1Fast,
   Veo31,

package/package.json

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