@shop-os/modelkit 0.4.7 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -34,6 +34,19 @@ type MediaRef = {
34
34
  /** Measured length of a video/audio; the kit never measures it. */
35
35
  durationSeconds?: number;
36
36
  };
37
+ /** A click on the image for `mask` rows, in source pixels; `background` excludes the spot. */
38
+ interface MaskPoint {
39
+ x: number;
40
+ y: number;
41
+ label?: "foreground" | "background";
42
+ }
43
+ /** A box around the object to mask, in source pixels. */
44
+ interface MaskBox {
45
+ xMin: number;
46
+ yMin: number;
47
+ xMax: number;
48
+ yMax: number;
49
+ }
37
50
  /** Caller-driven Topaz upscale controls; see the topaz row and TopazImageInput. */
38
51
  interface UpscaleOptions {
39
52
  enhanceModel?: string;
@@ -42,13 +55,83 @@ interface UpscaleOptions {
42
55
  faceEnhancementCreativity?: number;
43
56
  faceEnhancementStrength?: number;
44
57
  }
45
- type ModelType = "text" | "image" | "video" | "audio" | "upscale" | "bg-remove"
46
- /** Video in, video out, no prompt: upscale, frame interpolation, SDR to HDR. */
47
- | "video-tool";
58
+ type ModelType = "text" | "image" | "video" | "audio"
59
+ /** Sound effects (`generateAudio`): a text description, or a `sourceVideo` to score when the row requires one. */
60
+ | "sound-effect" | "upscale" | "bg-remove"
61
+ /** Image segmentation (`generateImage`): one image and a prompt in, one mask per match out. */
62
+ | "mask"
63
+ /** Video in, video out, no prompt: upscale, frame interpolation, SDR to HDR, background removal, subtitles. */
64
+ | "video-tool"
65
+ /** Text to speech (`generateSpeech`). */
66
+ | "speech"
67
+ /** Speech to speech in another voice (`changeVoice`). */
68
+ | "voice-change"
69
+ /** Speech translated into `targetLanguage` (`dub`), from a video or an audio file. */
70
+ | "dubbing"
71
+ /** A face driven by speech (`lipsync`): a `sourceVideo` re-timed or a still `image` animated. */
72
+ | "lipsync"
73
+ /** Speech to text (`transcribe`). */
74
+ | "transcription"
75
+ /** A prompt and/or photos of an object in, a GLB 3D model out. */
76
+ | "model3d";
77
+ /**
78
+ * How a `model3d` row's provider API is shaped. The adapter builds the request body and
79
+ * reads the result per family; everything a caller shows (inputs, views, options) is
80
+ * data on the row's `constraints.model3d`.
81
+ */
82
+ type Model3dFamily = "trellis" | "hunyuan" | "tripo" | "rodin" | "meshy" | "hi3d" | "sam";
83
+ /**
84
+ * How a `model3d` row takes extra views of the object:
85
+ * - `none`: one image only.
86
+ * - `unordered`: a list of images in any order (Meshy, Rodin).
87
+ * - `ordered`: front, left, back, right, contiguous from the front (Tripo).
88
+ * - `named`: one slot per side (Hunyuan, Hi3D).
89
+ */
90
+ type Model3dViews = "none" | "unordered" | "ordered" | "named";
91
+ type Model3dTexture = "none" | "standard" | "detailed";
92
+ /** fal paths a `model3d` row calls, by what the request carries. */
93
+ interface Model3dEndpoints {
94
+ /** A prompt and no image. */
95
+ text?: string;
96
+ /** One image. */
97
+ image?: string;
98
+ /** More than one image (the main image plus views). */
99
+ multiImage?: string;
100
+ }
101
+ /** What a `model3d` row takes and offers; see Model3dFamily. */
102
+ interface Model3dConstraints {
103
+ family: Model3dFamily;
104
+ endpoints: Model3dEndpoints;
105
+ /** Takes a text prompt (text-to-3D, or SAM's object name). */
106
+ text: boolean;
107
+ /** Needs an image whatever else is sent. */
108
+ imageRequired: boolean;
109
+ /** Needs a prompt whatever else is sent (SAM names the object to lift). */
110
+ promptRequired?: boolean;
111
+ views: Model3dViews;
112
+ /** Most images one request takes, the main image included. */
113
+ maxImages: number;
114
+ /** Texture choices; empty means the model has no texture switch. */
115
+ texture: Model3dTexture[];
116
+ pbr: boolean;
117
+ /** Takes a texture prompt and a texture image (Meshy). */
118
+ textureRef: boolean;
119
+ /** The provider takes a seed (for Meshy, only from a prompt). */
120
+ seed: boolean;
121
+ /** Largest seed the provider takes (Rodin: 65535); absent, any non-negative integer. */
122
+ seedMax?: number;
123
+ /** A quality or resolution choice the row prices by; absent when it has none. */
124
+ resolutions?: {
125
+ label: string;
126
+ options: string[];
127
+ default: string;
128
+ };
129
+ }
48
130
  /** What a `video-tool` row does to its source clip. */
49
- type VideoToolKind = "upscale" | "interpolate" | "hdr";
131
+ type VideoToolKind = "upscale" | "interpolate" | "hdr" | "bg-remove" | "subtitles";
50
132
  /** Container/codec a video-tool row can write. */
51
- type VideoToolOutputFormat = "h265" | "prores";
133
+ /** `exr`: a ZIP of 16-bit EXR frames in `VideoToolResult.frames`, with an MP4 preview as `video`. */
134
+ type VideoToolOutputFormat = "h265" | "prores" | "exr";
52
135
  type Lifecycle = "active" | "deprecated" | "retired";
53
136
  type Surface = "cowork" | "space_builder";
54
137
  /** @deprecated use Surface[] */
@@ -78,6 +161,10 @@ interface ImageRequest {
78
161
  temperature?: number;
79
162
  /** Upscaler controls beyond `scaleFactor`/`outputFormat` (Topaz). */
80
163
  upscale?: UpscaleOptions;
164
+ /** Mask rows with `supports: points`: spots that refine what the prompt selects. */
165
+ points?: MaskPoint[];
166
+ /** Mask rows with `supports: boxes`: boxes around the objects to mask. */
167
+ boxes?: MaskBox[];
81
168
  }
82
169
  /**
83
170
  * What a caller passes to generateImage. Same field names as the AI SDK's
@@ -125,6 +212,12 @@ interface VideoRequest {
125
212
  * adapter sends the prompt alone; `taskType: "extend"` still selects the extend path. */
126
213
  previousInteractionId?: string;
127
214
  mode?: "standard" | "pro";
215
+ /** Rows with `supports: ["insertWindow"]`: where the generated scene starts in the
216
+ * source clip and where the source footage resumes, in seconds. */
217
+ insertWindow?: {
218
+ startSeconds: number;
219
+ resumeSeconds: number;
220
+ };
128
221
  }
129
222
  /**
130
223
  * What a caller passes to generateVideo. `duration` is the AI SDK spelling of
@@ -152,12 +245,38 @@ interface VideoToolRequest {
152
245
  source: VideoToolSource;
153
246
  /** Upscale rows. */
154
247
  upscaleFactor?: number;
155
- /** Upscale rows whose `constraints.tool.prompt` is set; ignored by every other row. */
248
+ /** Rows whose `constraints.tool.prompt` is set; ignored by every other row. */
156
249
  prompt?: string;
157
250
  /** Interpolate rows. */
158
251
  targetFps?: number;
159
252
  /** HDR rows; the row's first `outputFormats` entry when unset. */
160
253
  outputFormat?: VideoToolOutputFormat;
254
+ /** Subtitles rows: caption style and language; the row's first preset when unset. */
255
+ subtitles?: SubtitleOptions;
256
+ }
257
+ /** Per-tier caption text overrides; an unset field keeps the preset's own. */
258
+ interface SubtitleTextStyle {
259
+ /** A Google Font name the provider supports. */
260
+ font?: string;
261
+ /** 100 to 900. */
262
+ weight?: number;
263
+ /** `#rgb` or `#rrggbb`. */
264
+ color?: string;
265
+ }
266
+ /** Burned-in caption options; every unset field keeps the preset's own. */
267
+ interface SubtitleOptions {
268
+ /** One of `constraints.tool.presets`. */
269
+ preset?: string;
270
+ /** The spoken language (one of `tool.languages`); the provider detects it when unset. */
271
+ language?: string;
272
+ /** Caption in this language instead (one of `tool.translationLanguages`). */
273
+ translationLanguage?: string;
274
+ position?: "top" | "center" | "bottom";
275
+ shadow?: "none" | "min" | "mid" | "max";
276
+ /** Every word. */
277
+ baseline?: SubtitleTextStyle;
278
+ /** The words the provider marks as key. */
279
+ highlighted?: SubtitleTextStyle;
161
280
  }
162
281
  /** The output a video-tool request will produce, from the request alone. */
163
282
  interface VideoToolOutputSpec {
@@ -165,8 +284,11 @@ interface VideoToolOutputSpec {
165
284
  height: number;
166
285
  durationSeconds: number;
167
286
  fps?: number;
287
+ /** HDR: the frames the row renders at `fps`, which the request sends. */
288
+ frames?: number;
168
289
  resolution: VideoResolution;
169
- format: "h264" | VideoToolOutputFormat;
290
+ /** `vp9` (WebM with alpha) is what a `bg-remove` row writes. */
291
+ format: "h264" | "vp9" | VideoToolOutputFormat;
170
292
  }
171
293
  interface VideoToolCallContext extends CallContext {
172
294
  /** Where the provider posts the result when the job ends. */
@@ -194,10 +316,79 @@ interface VideoToolResult {
194
316
  mime?: string;
195
317
  bytes?: number;
196
318
  };
319
+ /** The frame archive of an `exr` row; `video` is then its preview. */
320
+ frames?: {
321
+ url: string;
322
+ mime?: string;
323
+ bytes?: number;
324
+ };
197
325
  output: VideoToolOutputSpec;
198
326
  usage: UsageEvent;
199
327
  raw?: unknown;
200
328
  }
329
+ /** One 3D generation. Image URLs must be public; the provider fetches them. */
330
+ interface Model3dRequest {
331
+ model: string;
332
+ prompt?: string;
333
+ /** The main (front) image. */
334
+ image?: string;
335
+ /**
336
+ * Extra views of the same object; read only by rows whose `views` is not `none`. `top` is a
337
+ * fifth photo that only `unordered` rows send (all five fit Rodin's `maxImages` 5; Meshy sends
338
+ * the first 4 set); `named` and `ordered` rows have no slot for it and ignore it.
339
+ */
340
+ views?: {
341
+ back?: string;
342
+ left?: string;
343
+ right?: string;
344
+ top?: string;
345
+ };
346
+ /** Rows with `textureRef`. */
347
+ texturePrompt?: string;
348
+ textureImage?: string;
349
+ /** The row's `texture` default when unset; ignored by rows without a texture switch. */
350
+ texture?: Model3dTexture;
351
+ /** Rows with `pbr`; only applied to a textured model. */
352
+ pbr?: boolean;
353
+ /** One of the row's `resolutions.options`; its default when unset. */
354
+ resolution?: string;
355
+ /** Rows with `seed`. */
356
+ seed?: number;
357
+ }
358
+ /**
359
+ * A submitted 3D job. Plain JSON so a caller can store it and pass it back to
360
+ * `model3dStatus` / `model3dResult` / `cancelModel3d` from another process.
361
+ */
362
+ interface Model3dSubmission {
363
+ model: string;
364
+ provider: "fal";
365
+ /** The fal path the job went to. */
366
+ endpoint: string;
367
+ /** The priced option combination (pro-backend credit_pricing_flat model key). */
368
+ sku: string;
369
+ requestId: string;
370
+ statusUrl: string;
371
+ responseUrl: string;
372
+ cancelUrl: string;
373
+ /** Epoch ms when the kit submitted the job; the result's usage `latencyMs` is measured from it. */
374
+ submittedAt?: number;
375
+ }
376
+ type Model3dStatus = "queued" | "running" | "completed";
377
+ interface Model3dResult {
378
+ /** The binary glTF the provider made. */
379
+ glb: {
380
+ url: string;
381
+ mime?: string;
382
+ bytes?: number;
383
+ };
384
+ /** The provider's still of the model, when it returns one. */
385
+ thumbnail?: {
386
+ url: string;
387
+ };
388
+ sku: string;
389
+ usage: UsageEvent;
390
+ raw?: unknown;
391
+ }
201
392
  interface AudioRequest {
202
393
  model: string;
203
394
  prompt: string;
@@ -209,22 +400,118 @@ interface AudioRequest {
209
400
  seed?: number;
210
401
  /** Music models: no vocals. */
211
402
  instrumental?: boolean;
403
+ /** Music rows with `supports: lyrics`: the words to sing, with [verse]/[chorus] tags. */
404
+ lyrics?: string;
405
+ /** One of the row's `constraints.outputFormats`; the row default when unset. */
406
+ outputFormat?: string;
212
407
  /** Cancellation; combined with CallContext.signal before dispatch. */
213
408
  abortSignal?: AbortSignal;
214
409
  }
410
+ /** A provider file: a URL it hosts, or the bytes when it returns them inline. */
411
+ type MediaOutput = {
412
+ bytes: Uint8Array;
413
+ mime: string;
414
+ } | {
415
+ url: string;
416
+ mime?: string;
417
+ expiresAt?: Date;
418
+ };
215
419
  interface AudioResult {
216
- audio: {
217
- bytes: Uint8Array;
218
- mime: string;
219
- } | {
220
- url: string;
221
- expiresAt?: Date;
222
- };
420
+ audio: MediaOutput;
223
421
  /** Lyria returns lyrics as text parts next to the audio. */
224
422
  text?: string;
225
423
  usage: UsageEvent;
226
424
  raw?: JsonValue;
227
425
  }
426
+ /** `generateSpeech` on a `speech` row. Voice, language and format are ids the row lists. */
427
+ interface SpeechRequest {
428
+ model: string;
429
+ /** The script, spoken verbatim. */
430
+ text: string;
431
+ /** One of `constraints.voices[].id`; the row default when unset. */
432
+ voice?: string;
433
+ /** One of `constraints.languages[].code`; the provider detects it when unset. */
434
+ language?: string;
435
+ /** Rows with `supports: style`: how to speak it ("warm and slow"), kept out of the script. */
436
+ style?: string;
437
+ /** One of `constraints.outputFormats`; the row default when unset. */
438
+ outputFormat?: string;
439
+ abortSignal?: AbortSignal;
440
+ }
441
+ /** `changeVoice` on a `voice-change` row: the recording re-spoken in another voice. */
442
+ interface VoiceChangeRequest {
443
+ model: string;
444
+ /** Set `durationSeconds` so `constraints.references.audioSeconds` can be checked. */
445
+ sourceAudio: MediaRef;
446
+ voice?: string;
447
+ outputFormat?: string;
448
+ abortSignal?: AbortSignal;
449
+ }
450
+ /**
451
+ * `lipsync` on a `lipsync` row. The row's `requires` names the face input: `sourceVideo` (a
452
+ * video re-timed to the speech) or `firstFrame` (a still `image` animated).
453
+ */
454
+ interface LipsyncRequest {
455
+ model: string;
456
+ sourceVideo?: MediaRef;
457
+ image?: MediaRef;
458
+ /** The speech. Set `durationSeconds` so `constraints.references.audioSeconds` can be checked. */
459
+ audio: MediaRef;
460
+ /** Rows that list `constraints.resolutions`; the row default when unset. */
461
+ resolution?: VideoResolution;
462
+ abortSignal?: AbortSignal;
463
+ }
464
+ interface LipsyncResult {
465
+ video: MediaOutput;
466
+ usage: UsageEvent;
467
+ raw?: unknown;
468
+ }
469
+ /** `dub` on a `dubbing` row: exactly one of `sourceVideo` / `sourceAudio`. */
470
+ interface DubbingRequest {
471
+ model: string;
472
+ sourceVideo?: MediaRef;
473
+ sourceAudio?: MediaRef;
474
+ /** One of `constraints.languages[].code`. */
475
+ targetLanguage: string;
476
+ /** One of `constraints.outputFormats` on rows that list them. */
477
+ outputFormat?: string;
478
+ abortSignal?: AbortSignal;
479
+ }
480
+ /** The dubbed media, of the same kind as the source. */
481
+ interface DubbingResult {
482
+ video?: MediaOutput;
483
+ audio?: MediaOutput;
484
+ usage: UsageEvent;
485
+ raw?: unknown;
486
+ }
487
+ interface TranscriptionRequest {
488
+ model: string;
489
+ /** The speech, audio or video. Set `durationSeconds` so limits and usage can use it. */
490
+ source: MediaRef;
491
+ /** One of `constraints.languages[].code`; the provider detects the language when unset. */
492
+ language?: string;
493
+ /** Also return `subtitles` (SRT) built from the word timings. */
494
+ timestamps?: boolean;
495
+ abortSignal?: AbortSignal;
496
+ }
497
+ interface TranscriptWord {
498
+ text: string;
499
+ /** `word`, `spacing` or `audio_event` (ElevenLabs Scribe). */
500
+ type: string;
501
+ start?: number;
502
+ end?: number;
503
+ speakerId?: string;
504
+ }
505
+ interface TranscriptionResult {
506
+ text: string;
507
+ /** SubRip (SRT) cues, when the request asked for `timestamps`. */
508
+ subtitles?: string;
509
+ /** The language the provider detected or was told. */
510
+ language?: string;
511
+ words: TranscriptWord[];
512
+ usage: UsageEvent;
513
+ raw?: JsonValue;
514
+ }
228
515
  /** An AI SDK file part ready for generateText/generateObject, e.g. a video for understanding. */
229
516
  interface MediaPart {
230
517
  type: "file";
@@ -233,10 +520,18 @@ interface MediaPart {
233
520
  /** Set when the bytes were uploaded to a provider file store (Gemini Files API). Call `cleanup` after the request. */
234
521
  cleanup?: () => Promise<void>;
235
522
  }
236
- type RequiredInput = "firstFrame" | "sourceVideo" | "references";
523
+ type RequiredInput = "firstFrame" | "sourceVideo" | "references" | "sourceAudio";
237
524
  type SupportedOption = "seed" | "quality" | "negativePrompt" | "cfgScale" | "generateAudio" | "promptExpansion" | "lastFrame" | "count" | "outputFormat" | "scaleFactor" | "safetySettings" | "temperature" | "upscale" | "watermark" | "safetyChecker" | "taskType" | "instrumental"
525
+ /** Music rows that sing `AudioRequest.lyrics`. */
526
+ | "lyrics"
527
+ /** Speech rows that take `SpeechRequest.style`, a delivery instruction. */
528
+ | "style"
238
529
  /** Video rows that extend a clip in fixed segments up to a cumulative cap (see `ModelConstraints.extension`). */
239
- | "videoExtension";
530
+ | "videoExtension"
531
+ /** Video rows that generate a scene inside a source clip (`VideoRequest.insertWindow`). */
532
+ | "insertWindow"
533
+ /** Mask rows: `ImageRequest.points` and `ImageRequest.boxes`. */
534
+ | "points" | "boxes";
240
535
  interface VideoSecondsLimits {
241
536
  /** Minimum length of each reference video, in seconds. */
242
537
  min?: number;
@@ -268,6 +563,16 @@ interface ReferenceLimits {
268
563
  audioFormats?: string[];
269
564
  /** Largest reference audio file the provider takes, in bytes. */
270
565
  audioMaxBytes?: number;
566
+ /**
567
+ * Video rows: the fewest references of each kind a request needs (Kling 3.0 Motion Control:
568
+ * one image and one video). `requires: ["references"]` needs one of any kind; this names
569
+ * the kinds. Kits before 0.5.0 ignore it.
570
+ */
571
+ min?: {
572
+ images?: number;
573
+ videos?: number;
574
+ audios?: number;
575
+ };
271
576
  }
272
577
  interface VideoToolConstraints {
273
578
  kind: VideoToolKind;
@@ -278,7 +583,7 @@ interface VideoToolConstraints {
278
583
  };
279
584
  /** Upscale: the output's long edge may not pass this, in pixels. */
280
585
  maxOutputLongEdge?: number;
281
- /** Upscale: the row takes an optional prompt that guides added detail. */
586
+ /** Upscale and HDR: the row takes an optional prompt that guides the result. */
282
587
  prompt?: boolean;
283
588
  /** Interpolate: allowed target frame rate range. */
284
589
  fps?: {
@@ -287,11 +592,45 @@ interface VideoToolConstraints {
287
592
  };
288
593
  /** HDR: the formats the row writes, first is the default. */
289
594
  outputFormats?: VideoToolOutputFormat[];
595
+ /** The output's short edge is scaled down to this many pixels, keeping the aspect ratio. */
596
+ maxOutputShortEdge?: number;
597
+ /** The most frames the row renders (duration times frame rate). */
598
+ maxOutputFrames?: number;
599
+ /** HDR: the fewest frames the row renders; a shorter source is padded to it. */
600
+ minOutputFrames?: number;
601
+ /** HDR: the fastest output rate; a faster source renders at this rate. */
602
+ maxOutputFps?: number;
603
+ /** Subtitles: the caption styles, first is the default. */
604
+ presets?: string[];
605
+ /** Subtitles: spoken-language codes the provider transcribes. */
606
+ languages?: string[];
607
+ /** Subtitles: codes the provider can translate the captions into. */
608
+ translationLanguages?: string[];
609
+ /** Subtitles: the longest source above 1080p, in seconds (`sourceVideoSeconds.max` covers the rest). */
610
+ maxSecondsAbove1080p?: number;
290
611
  }
291
612
  /** Whether a video row's output has sound: always, switchable (`supports: generateAudio`), or silent. */
292
613
  type AudioOutput = "always" | "optional" | "never";
293
614
  /** How a prompt points at reference N: "image N" numbering, a caption beside each image, or prose. */
294
615
  type ReferenceSyntax = "numbered" | "caption" | "descriptive";
616
+ type VoiceGender = "male" | "female" | "neutral";
617
+ /** A voice a row offers. `id` is the value sent to the provider. */
618
+ interface VoiceOption {
619
+ id: string;
620
+ name: string;
621
+ gender?: VoiceGender;
622
+ accent?: string;
623
+ /** Language codes the provider lists for the voice. */
624
+ languages?: string[];
625
+ description?: string;
626
+ /** An https sample of the voice. */
627
+ previewUrl?: string;
628
+ }
629
+ /** A language a row takes. `code` is the value sent to the provider. */
630
+ interface LanguageOption {
631
+ code: string;
632
+ name: string;
633
+ }
295
634
  interface PromptConventions {
296
635
  referenceSyntax: ReferenceSyntax;
297
636
  /** Provider-documented prompt length limit, in characters. */
@@ -309,6 +648,8 @@ interface ModelConstraints {
309
648
  durationPresets?: number[];
310
649
  /** Curated quality choices for rows whose `supports` includes "quality". */
311
650
  qualityOptions?: string[];
651
+ /** Upscale rows: the `scaleFactor` values the row offers; absent means any. */
652
+ scaleFactors?: number[];
312
653
  /**
313
654
  * Exact pixel size per aspect ratio for rows an app must size verbatim
314
655
  * (gpt-image-2 keeps its historic WxH contract); callers pass it as `exactSize`.
@@ -316,9 +657,26 @@ interface ModelConstraints {
316
657
  exactSizes?: Record<string, string>;
317
658
  references?: ReferenceLimits;
318
659
  requires?: RequiredInput[];
660
+ /**
661
+ * Video rows: at least one of these inputs must be present (`requires` needs all of its
662
+ * own). Kits before 0.5.0 ignore it.
663
+ */
664
+ requiresOneOf?: RequiredInput[];
665
+ /**
666
+ * Video rows whose endpoint has no prompt field (MiniMax H3 Max Relight): the request needs
667
+ * no prompt, and a non-empty one is dropped with an `option_ignored` warning. Absent means
668
+ * the row takes a prompt. Kits before 0.5.0 ignore it.
669
+ */
670
+ noPrompt?: boolean;
319
671
  supports?: SupportedOption[];
320
672
  /** Ratio is dropped, with a warning, when one of these inputs is present. */
321
673
  ratioIgnoredWith?: ("firstFrame" | "sourceVideo")[];
674
+ /** Speech and voice-change rows: the voices offered; `defaults.voice` is one of their ids. */
675
+ voices?: VoiceOption[];
676
+ /** Speech, transcription and dubbing (target) rows: the languages taken. */
677
+ languages?: LanguageOption[];
678
+ /** Audio-output rows whose provider lets the caller pick a file format; `defaults.outputFormat` is one. */
679
+ outputFormats?: string[];
322
680
  /** Length limits for the source video the row edits or extends. */
323
681
  sourceVideoSeconds?: Omit<VideoSecondsLimits, "total"> & {
324
682
  /** The provider sends the source as a reference video, so it counts toward `references.videoSeconds.total` (Seedance). */
@@ -335,6 +693,8 @@ interface ModelConstraints {
335
693
  };
336
694
  /** What a `video-tool` row accepts. Read it through `videoToolConstraints(row)`. */
337
695
  tool?: VideoToolConstraints;
696
+ /** Required on `model3d` rows. */
697
+ model3d?: Model3dConstraints;
338
698
  /** Whether the output has sound. Read it through `outputAudio(row)`, which tolerates bad data. */
339
699
  audio?: AudioOutput;
340
700
  /** Prompt conventions. Read them through `promptConventions(row)`, which fills the default. */
@@ -360,7 +720,8 @@ type ProviderOptions = {
360
720
  [key: string]: ProviderOptionValue;
361
721
  };
362
722
  };
363
- type UsageUnit = "tokens" | "images" | "seconds" | "reported_cost_usd" | "compute_seconds";
723
+ /** `requests`: one call billed at a flat price per request (a 3D job); the usage sink's `REQUESTS`. */
724
+ type UsageUnit = "tokens" | "images" | "seconds" | "reported_cost_usd" | "compute_seconds" | "requests";
364
725
  type UsageModality = "TEXT" | "IMAGE" | "VIDEO" | "AUDIO";
365
726
  type PricingKind = "token" | "image_size" | "video_per_second" | "flat";
366
727
  /** What a model picker shows for a row. Free of any surface-specific ids. */
@@ -411,6 +772,15 @@ interface CatalogCapabilities {
411
772
  vision?: boolean;
412
773
  contextWindow?: number;
413
774
  }
775
+ /** Row defaults the request types do not share. */
776
+ interface MediaNodeDefaults {
777
+ /** Image rows: png, jpeg or webp. Audio-output rows: one of `constraints.outputFormats`. */
778
+ outputFormat?: string;
779
+ /** One of `constraints.voices[].id`. */
780
+ voice?: string;
781
+ /** One of `constraints.languages[].code`. */
782
+ language?: string;
783
+ }
414
784
  interface CatalogModel {
415
785
  /** Canonical id. Equals the pricing key in pro-backend credit_pricing_* tables. */
416
786
  id: string;
@@ -430,7 +800,7 @@ interface CatalogModel {
430
800
  */
431
801
  exposure: Surface[];
432
802
  constraints: ModelConstraints;
433
- defaults: Partial<Omit<ImageRequest, "model" | "prompt"> & Omit<VideoRequest, "model" | "prompt"> & Omit<AudioRequest, "model" | "prompt">>;
803
+ defaults: Partial<Omit<ImageRequest, "model" | "prompt" | "outputFormat"> & Omit<VideoRequest, "model" | "prompt"> & Omit<AudioRequest, "model" | "prompt" | "outputFormat">> & MediaNodeDefaults;
434
804
  /** Provider options merged under the caller's on every call. Chat-only tuning belongs in display.chat. */
435
805
  providerOptions?: ProviderOptions;
436
806
  /**
@@ -676,7 +1046,11 @@ declare function isListedOn(row: CatalogModel, surface: Surface): boolean;
676
1046
  /** True when an active row is listed on at least one surface. */
677
1047
  declare function isListed(row: CatalogModel): boolean;
678
1048
 
679
- /** Seeded from Cowork, Space Builder and trigger-workflows. See catalog/*.ts. */
1049
+ /**
1050
+ * Every row, aggregated from the exported per-type collections only, so a row added anywhere
1051
+ * else never reaches MODELS without its collection. Seeded from Cowork, Space Builder and
1052
+ * trigger-workflows. See catalog/*.ts.
1053
+ */
680
1054
  declare const MODELS: CatalogModel[];
681
1055
 
682
1056
  declare const ADAPTER_IDS: readonly ["ai-sdk-text", "google-image", "openai-image", "google-genai", "ark", "fal", "replicate", "prodia", "higgsfield", "xai-video"];
@@ -704,9 +1078,17 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
704
1078
  image: "image";
705
1079
  video: "video";
706
1080
  audio: "audio";
1081
+ "sound-effect": "sound-effect";
707
1082
  upscale: "upscale";
708
1083
  "bg-remove": "bg-remove";
1084
+ mask: "mask";
709
1085
  "video-tool": "video-tool";
1086
+ speech: "speech";
1087
+ "voice-change": "voice-change";
1088
+ dubbing: "dubbing";
1089
+ lipsync: "lipsync";
1090
+ transcription: "transcription";
1091
+ model3d: "model3d";
710
1092
  }>;
711
1093
  adapter: z.ZodEnum<{
712
1094
  "ai-sdk-text": "ai-sdk-text";
@@ -769,6 +1151,7 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
769
1151
  }, z.core.$loose>, z.ZodArray<z.ZodNumber>]>>;
770
1152
  durationPresets: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
771
1153
  qualityOptions: z.ZodOptional<z.ZodArray<z.ZodString>>;
1154
+ scaleFactors: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
772
1155
  exactSizes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
773
1156
  references: z.ZodOptional<z.ZodObject<{
774
1157
  images: z.ZodOptional<z.ZodNumber>;
@@ -790,12 +1173,25 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
790
1173
  }, z.core.$loose>>;
791
1174
  audioFormats: z.ZodOptional<z.ZodArray<z.ZodString>>;
792
1175
  audioMaxBytes: z.ZodOptional<z.ZodNumber>;
1176
+ min: z.ZodOptional<z.ZodObject<{
1177
+ images: z.ZodOptional<z.ZodNumber>;
1178
+ videos: z.ZodOptional<z.ZodNumber>;
1179
+ audios: z.ZodOptional<z.ZodNumber>;
1180
+ }, z.core.$loose>>;
793
1181
  }, z.core.$loose>>;
794
1182
  requires: z.ZodOptional<z.ZodArray<z.ZodEnum<{
795
1183
  references: "references";
796
1184
  firstFrame: "firstFrame";
797
1185
  sourceVideo: "sourceVideo";
1186
+ sourceAudio: "sourceAudio";
798
1187
  }>>>;
1188
+ requiresOneOf: z.ZodOptional<z.ZodArray<z.ZodEnum<{
1189
+ references: "references";
1190
+ firstFrame: "firstFrame";
1191
+ sourceVideo: "sourceVideo";
1192
+ sourceAudio: "sourceAudio";
1193
+ }>>>;
1194
+ noPrompt: z.ZodOptional<z.ZodBoolean>;
799
1195
  supports: z.ZodOptional<z.ZodArray<z.ZodEnum<{
800
1196
  upscale: "upscale";
801
1197
  quality: "quality";
@@ -805,6 +1201,8 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
805
1201
  scaleFactor: "scaleFactor";
806
1202
  safetySettings: "safetySettings";
807
1203
  temperature: "temperature";
1204
+ points: "points";
1205
+ boxes: "boxes";
808
1206
  lastFrame: "lastFrame";
809
1207
  generateAudio: "generateAudio";
810
1208
  negativePrompt: "negativePrompt";
@@ -813,13 +1211,34 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
813
1211
  watermark: "watermark";
814
1212
  safetyChecker: "safetyChecker";
815
1213
  taskType: "taskType";
1214
+ insertWindow: "insertWindow";
816
1215
  instrumental: "instrumental";
1216
+ lyrics: "lyrics";
1217
+ style: "style";
817
1218
  videoExtension: "videoExtension";
818
1219
  }>>>;
819
1220
  ratioIgnoredWith: z.ZodOptional<z.ZodArray<z.ZodEnum<{
820
1221
  firstFrame: "firstFrame";
821
1222
  sourceVideo: "sourceVideo";
822
1223
  }>>>;
1224
+ voices: z.ZodOptional<z.ZodArray<z.ZodObject<{
1225
+ id: z.ZodString;
1226
+ name: z.ZodString;
1227
+ gender: z.ZodOptional<z.ZodEnum<{
1228
+ male: "male";
1229
+ female: "female";
1230
+ neutral: "neutral";
1231
+ }>>;
1232
+ accent: z.ZodOptional<z.ZodString>;
1233
+ languages: z.ZodOptional<z.ZodArray<z.ZodString>>;
1234
+ description: z.ZodOptional<z.ZodString>;
1235
+ previewUrl: z.ZodOptional<z.ZodURL>;
1236
+ }, z.core.$loose>>>;
1237
+ languages: z.ZodOptional<z.ZodArray<z.ZodObject<{
1238
+ code: z.ZodString;
1239
+ name: z.ZodString;
1240
+ }, z.core.$loose>>>;
1241
+ outputFormats: z.ZodOptional<z.ZodArray<z.ZodString>>;
823
1242
  sourceVideoSeconds: z.ZodOptional<z.ZodObject<{
824
1243
  max: z.ZodOptional<z.ZodNumber>;
825
1244
  min: z.ZodOptional<z.ZodNumber>;
@@ -837,8 +1256,10 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
837
1256
  tool: z.ZodOptional<z.ZodObject<{
838
1257
  kind: z.ZodEnum<{
839
1258
  upscale: "upscale";
1259
+ "bg-remove": "bg-remove";
840
1260
  interpolate: "interpolate";
841
1261
  hdr: "hdr";
1262
+ subtitles: "subtitles";
842
1263
  }>;
843
1264
  upscaleFactor: z.ZodOptional<z.ZodObject<{
844
1265
  min: z.ZodNumber;
@@ -853,7 +1274,56 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
853
1274
  outputFormats: z.ZodOptional<z.ZodArray<z.ZodEnum<{
854
1275
  h265: "h265";
855
1276
  prores: "prores";
1277
+ exr: "exr";
856
1278
  }>>>;
1279
+ maxOutputShortEdge: z.ZodOptional<z.ZodNumber>;
1280
+ maxOutputFrames: z.ZodOptional<z.ZodNumber>;
1281
+ minOutputFrames: z.ZodOptional<z.ZodNumber>;
1282
+ maxOutputFps: z.ZodOptional<z.ZodNumber>;
1283
+ presets: z.ZodOptional<z.ZodArray<z.ZodString>>;
1284
+ languages: z.ZodOptional<z.ZodArray<z.ZodString>>;
1285
+ translationLanguages: z.ZodOptional<z.ZodArray<z.ZodString>>;
1286
+ maxSecondsAbove1080p: z.ZodOptional<z.ZodNumber>;
1287
+ }, z.core.$loose>>;
1288
+ model3d: z.ZodOptional<z.ZodObject<{
1289
+ family: z.ZodEnum<{
1290
+ trellis: "trellis";
1291
+ hunyuan: "hunyuan";
1292
+ tripo: "tripo";
1293
+ rodin: "rodin";
1294
+ meshy: "meshy";
1295
+ hi3d: "hi3d";
1296
+ sam: "sam";
1297
+ }>;
1298
+ endpoints: z.ZodObject<{
1299
+ text: z.ZodOptional<z.ZodString>;
1300
+ image: z.ZodOptional<z.ZodString>;
1301
+ multiImage: z.ZodOptional<z.ZodString>;
1302
+ }, z.core.$loose>;
1303
+ text: z.ZodBoolean;
1304
+ imageRequired: z.ZodBoolean;
1305
+ promptRequired: z.ZodOptional<z.ZodBoolean>;
1306
+ views: z.ZodEnum<{
1307
+ none: "none";
1308
+ unordered: "unordered";
1309
+ ordered: "ordered";
1310
+ named: "named";
1311
+ }>;
1312
+ maxImages: z.ZodNumber;
1313
+ texture: z.ZodArray<z.ZodEnum<{
1314
+ none: "none";
1315
+ standard: "standard";
1316
+ detailed: "detailed";
1317
+ }>>;
1318
+ pbr: z.ZodBoolean;
1319
+ textureRef: z.ZodBoolean;
1320
+ seed: z.ZodBoolean;
1321
+ seedMax: z.ZodOptional<z.ZodNumber>;
1322
+ resolutions: z.ZodOptional<z.ZodObject<{
1323
+ label: z.ZodString;
1324
+ options: z.ZodArray<z.ZodString>;
1325
+ default: z.ZodString;
1326
+ }, z.core.$loose>>;
857
1327
  }, z.core.$loose>>;
858
1328
  audio: z.ZodOptional<z.ZodUnknown>;
859
1329
  prompt: z.ZodOptional<z.ZodUnknown>;
@@ -905,11 +1375,11 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
905
1375
  }>>;
906
1376
  seed: z.ZodOptional<z.ZodNumber>;
907
1377
  count: z.ZodOptional<z.ZodNumber>;
908
- outputFormat: z.ZodOptional<z.ZodEnum<{
1378
+ outputFormat: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
909
1379
  png: "png";
910
1380
  jpeg: "jpeg";
911
1381
  webp: "webp";
912
- }>>;
1382
+ }>, z.ZodString]>>;
913
1383
  scaleFactor: z.ZodOptional<z.ZodNumber>;
914
1384
  safetySettings: z.ZodOptional<z.ZodArray<z.ZodObject<{
915
1385
  category: z.ZodString;
@@ -923,6 +1393,20 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
923
1393
  faceEnhancementCreativity: z.ZodOptional<z.ZodNumber>;
924
1394
  faceEnhancementStrength: z.ZodOptional<z.ZodNumber>;
925
1395
  }, z.core.$loose>>;
1396
+ points: z.ZodOptional<z.ZodArray<z.ZodObject<{
1397
+ x: z.ZodNumber;
1398
+ y: z.ZodNumber;
1399
+ label: z.ZodOptional<z.ZodEnum<{
1400
+ foreground: "foreground";
1401
+ background: "background";
1402
+ }>>;
1403
+ }, z.core.$loose>>>;
1404
+ boxes: z.ZodOptional<z.ZodArray<z.ZodObject<{
1405
+ xMin: z.ZodNumber;
1406
+ yMin: z.ZodNumber;
1407
+ xMax: z.ZodNumber;
1408
+ yMax: z.ZodNumber;
1409
+ }, z.core.$loose>>>;
926
1410
  firstFrame: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
927
1411
  url: z.ZodString;
928
1412
  label: z.ZodOptional<z.ZodString>;
@@ -1003,6 +1487,10 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
1003
1487
  }>>;
1004
1488
  watermark: z.ZodOptional<z.ZodBoolean>;
1005
1489
  safetyChecker: z.ZodOptional<z.ZodBoolean>;
1490
+ insertWindow: z.ZodOptional<z.ZodObject<{
1491
+ startSeconds: z.ZodNumber;
1492
+ resumeSeconds: z.ZodNumber;
1493
+ }, z.core.$loose>>;
1006
1494
  taskType: z.ZodOptional<z.ZodEnum<{
1007
1495
  reference: "reference";
1008
1496
  edit: "edit";
@@ -1013,6 +1501,9 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
1013
1501
  pro: "pro";
1014
1502
  }>>;
1015
1503
  instrumental: z.ZodOptional<z.ZodBoolean>;
1504
+ lyrics: z.ZodOptional<z.ZodString>;
1505
+ voice: z.ZodOptional<z.ZodString>;
1506
+ language: z.ZodOptional<z.ZodString>;
1016
1507
  }, z.core.$loose>;
1017
1508
  providerOptions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<ProviderOptionValue, unknown, z.core.$ZodTypeInternals<ProviderOptionValue, unknown>>>>>;
1018
1509
  usage: z.ZodObject<{
@@ -1022,6 +1513,7 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
1022
1513
  seconds: "seconds";
1023
1514
  reported_cost_usd: "reported_cost_usd";
1024
1515
  compute_seconds: "compute_seconds";
1516
+ requests: "requests";
1025
1517
  }>;
1026
1518
  slug: z.ZodOptional<z.ZodString>;
1027
1519
  providerLabel: z.ZodOptional<z.ZodString>;
@@ -1144,6 +1636,14 @@ interface AdapterContext {
1144
1636
  call: CallContext;
1145
1637
  warnings: Warning[];
1146
1638
  }
1639
+ /** A dubbed video is a provider job the client waits on; dubbed audio arrives in one call. */
1640
+ type DubbingOutcome = {
1641
+ kind: "video";
1642
+ job: VideoJob;
1643
+ } | {
1644
+ kind: "audio";
1645
+ result: AudioResult;
1646
+ };
1147
1647
  /**
1148
1648
  * One adapter per provider API. The request the adapter receives has already
1149
1649
  * passed resolveOptions: every option is inside the catalog constraints and the
@@ -1156,6 +1656,11 @@ interface Adapter {
1156
1656
  /** Reconnect to a job `generateVideo` submitted earlier; never submits. */
1157
1657
  resumeVideo?(req: VideoRequest, jobId: string, ctx: AdapterContext): VideoJob;
1158
1658
  generateAudio?(req: AudioRequest, ctx: AdapterContext): Promise<AudioResult>;
1659
+ generateSpeech?(req: SpeechRequest, ctx: AdapterContext): Promise<AudioResult>;
1660
+ changeVoice?(req: VoiceChangeRequest, ctx: AdapterContext): Promise<AudioResult>;
1661
+ lipsync?(req: LipsyncRequest, ctx: AdapterContext): Promise<VideoJob>;
1662
+ dub?(req: DubbingRequest, ctx: AdapterContext): Promise<DubbingOutcome>;
1663
+ transcribe?(req: TranscriptionRequest, ctx: AdapterContext): Promise<TranscriptionResult>;
1159
1664
  /** Video tools run as provider jobs the caller tracks; see ModelKit.submitVideoTool. */
1160
1665
  submitVideoTool?(req: VideoToolRequest, ctx: AdapterContext, opts: {
1161
1666
  webhookUrl?: string;
@@ -1163,6 +1668,13 @@ interface Adapter {
1163
1668
  videoToolStatus?(sub: VideoToolSubmission, ctx: AdapterContext): Promise<VideoToolStatus>;
1164
1669
  videoToolResult?(sub: VideoToolSubmission, ctx: AdapterContext, webhook?: FalWebhookBody): Promise<VideoToolResult>;
1165
1670
  cancelVideoTool?(sub: VideoToolSubmission, ctx: AdapterContext): Promise<boolean>;
1671
+ /** 3D models run as provider jobs the caller tracks; see ModelKit.submitModel3d. */
1672
+ submitModel3d?(req: Model3dRequest, ctx: AdapterContext, opts: {
1673
+ webhookUrl?: string;
1674
+ }): Promise<Model3dSubmission>;
1675
+ model3dStatus?(sub: Model3dSubmission, ctx: AdapterContext): Promise<Model3dStatus>;
1676
+ model3dResult?(sub: Model3dSubmission, ctx: AdapterContext, webhook?: FalWebhookBody): Promise<Model3dResult>;
1677
+ cancelModel3d?(sub: Model3dSubmission, ctx: AdapterContext): Promise<boolean>;
1166
1678
  /**
1167
1679
  * Turn a media reference into an AI SDK file part the provider's language
1168
1680
  * model accepts. Google uploads large videos through the Files API.
@@ -1254,6 +1766,17 @@ declare function resolveImageOptions(model: CatalogModel, request: ImageRequest,
1254
1766
  declare function resolveVideoOptions(model: CatalogModel, request: VideoRequest, onUnsupported?: OnUnsupported): ResolveResult<VideoRequest>;
1255
1767
  declare function resolveAudioOptions(model: CatalogModel, request: AudioRequest, onUnsupported?: OnUnsupported): ResolveResult<AudioRequest>;
1256
1768
 
1769
+ /** `generateSpeech` on a `speech` row. */
1770
+ declare function resolveSpeechOptions(model: CatalogModel, request: SpeechRequest, onUnsupported?: OnUnsupported): ResolveResult<SpeechRequest>;
1771
+ /** `changeVoice` on a `voice-change` row. */
1772
+ declare function resolveVoiceChangeOptions(model: CatalogModel, request: VoiceChangeRequest, onUnsupported?: OnUnsupported): ResolveResult<VoiceChangeRequest>;
1773
+ /** `lipsync` on a `lipsync` row: the face input is the one its `requires` names. */
1774
+ declare function resolveLipsyncOptions(model: CatalogModel, request: LipsyncRequest, onUnsupported?: OnUnsupported): ResolveResult<LipsyncRequest>;
1775
+ /** `dub` on a `dubbing` row: one source, a target language the row lists. */
1776
+ declare function resolveDubbingOptions(model: CatalogModel, request: DubbingRequest, onUnsupported?: OnUnsupported): ResolveResult<DubbingRequest>;
1777
+ /** `transcribe` on a `transcription` row. */
1778
+ declare function resolveTranscriptionOptions(model: CatalogModel, request: TranscriptionRequest, onUnsupported?: OnUnsupported): ResolveResult<TranscriptionRequest>;
1779
+
1257
1780
  /** Which key names an adapter needs. All of them must be set on a tier for that tier to win. */
1258
1781
  declare const ADAPTER_KEYS: Record<AdapterId, ProviderKeyName[]>;
1259
1782
  /** The required names the given non-pro tier is missing. */
@@ -1293,6 +1816,27 @@ declare function pollUntil<T>(check: () => Promise<T | undefined>, opts: {
1293
1816
  maxIntervalMs?: number;
1294
1817
  }): Promise<T>;
1295
1818
 
1819
+ /** `lipsync` and a video `dub` wait on a provider job; `wait` tunes that wait. */
1820
+ interface MediaJobCallContext extends CallContext {
1821
+ wait?: {
1822
+ pollIntervalMs?: number;
1823
+ timeoutMs?: number;
1824
+ };
1825
+ }
1826
+ /** The single-purpose audio and lipsync node methods of the kit. */
1827
+ interface AudioNodeMethods {
1828
+ /** Text to speech on a `speech` row. Blocks until the provider returns the audio. */
1829
+ generateSpeech(req: SpeechRequest, call?: CallContext): Promise<AudioResult>;
1830
+ /** Re-speaks a recording in another voice on a `voice-change` row. */
1831
+ changeVoice(req: VoiceChangeRequest, call?: CallContext): Promise<AudioResult>;
1832
+ /** Drives a face (`sourceVideo` or `image`) with speech on a `lipsync` row. */
1833
+ lipsync(req: LipsyncRequest, call?: MediaJobCallContext): Promise<LipsyncResult>;
1834
+ /** Speech to text on a `transcription` row; `timestamps` adds SRT `subtitles`. */
1835
+ transcribe(req: TranscriptionRequest, call?: CallContext): Promise<TranscriptionResult>;
1836
+ /** Dubs a video or an audio file into `targetLanguage`; the result is the same kind. */
1837
+ dub(req: DubbingRequest, call?: MediaJobCallContext): Promise<DubbingResult>;
1838
+ }
1839
+
1296
1840
  /**
1297
1841
  * The AI SDK `LanguageModel` type. A string is a catalog id or alias; a provider
1298
1842
  * instance (`openai("gpt-4o")`) runs through the SDK unchanged, with usage
@@ -1349,7 +1893,7 @@ type StreamTextCallOptions<TOOLS extends ToolSet, OUTPUT extends Output.Output =
1349
1893
  /** @deprecated Use `prepareStep`; accepted for parity with `generateText`. */
1350
1894
  experimental_prepareStep?: Parameters<typeof streamText$1<TOOLS, OUTPUT>>[0]["prepareStep"];
1351
1895
  };
1352
- interface ModelKit extends TextMethods {
1896
+ interface ModelKit extends TextMethods, AudioNodeMethods {
1353
1897
  catalog: Catalog;
1354
1898
  /**
1355
1899
  * Generate one or more images. Blocks until the provider returns bytes.
@@ -1371,7 +1915,11 @@ interface ModelKit extends TextMethods {
1371
1915
  languageModel(modelId: string, call?: CallContext): LanguageModelHandle;
1372
1916
  /** Usage-event `provider` for a catalog model, without building it: "bedrock" on Bedrock, else the vendor. */
1373
1917
  usageProvider(modelId: string, call?: CallContext): string;
1374
- /** Generate music or a soundtrack. Blocks until the provider returns audio. */
1918
+ /**
1919
+ * Generate music (`audio`) or a sound effect (`sound-effect`). Blocks until the provider
1920
+ * returns audio. Speech, voice change, lipsync, dubbing and transcription have their own
1921
+ * methods (AudioNodeMethods).
1922
+ */
1375
1923
  generateAudio(req: AudioRequest, call?: CallContext): Promise<AudioResult>;
1376
1924
  /**
1377
1925
  * Stream text. Mirrors `TextMethods.streamText` and also accepts the
@@ -1400,6 +1948,21 @@ interface ModelKit extends TextMethods {
1400
1948
  }): Promise<VideoToolResult>;
1401
1949
  /** True when the provider accepted the cancel, false when the job had already ended. */
1402
1950
  cancelVideoTool(sub: VideoToolSubmission, call?: CallContext): Promise<boolean>;
1951
+ /**
1952
+ * Start a 3D generation (`type: "model3d"`) and return without waiting. Store the
1953
+ * submission; the provider posts to `call.webhookUrl` when the job ends.
1954
+ */
1955
+ submitModel3d(req: Model3dRequest, call?: VideoToolCallContext): Promise<Model3dSubmission>;
1956
+ model3dStatus(sub: Model3dSubmission, call?: CallContext): Promise<Model3dStatus>;
1957
+ /**
1958
+ * The finished model. Pass the verified webhook body when there is one; without it the
1959
+ * kit fetches the provider's stored result. Emits the usage event.
1960
+ */
1961
+ model3dResult(sub: Model3dSubmission, call?: CallContext & {
1962
+ webhook?: FalWebhookBody;
1963
+ }): Promise<Model3dResult>;
1964
+ /** True when the provider accepted the cancel, false when the job had already ended. */
1965
+ cancelModel3d(sub: Model3dSubmission, call?: CallContext): Promise<boolean>;
1403
1966
  }
1404
1967
  interface LanguageModelHandle {
1405
1968
  model: LanguageModelV3;
@@ -1473,6 +2036,72 @@ declare function planVideoTool(row: CatalogModel, req: Omit<VideoToolRequest, "m
1473
2036
  */
1474
2037
  declare const VIDEO_TOOL_MODELS: CatalogModel[];
1475
2038
 
2039
+ /**
2040
+ * 3D generation on fal: the newest model of each 3D family. A request's price depends on
2041
+ * its options (texture, PBR, views, resolution), so each row bills one flat price per
2042
+ * option combination: `model3dSkus(row)` lists them and pro-backend keeps a
2043
+ * credit_pricing_flat row for each.
2044
+ */
2045
+ declare const MODEL3D_MODELS: CatalogModel[];
2046
+
2047
+ /** A `model3d` row's spec, or undefined for any other row. */
2048
+ declare function model3dConstraints(row: CatalogModel): Model3dConstraints | undefined;
2049
+ /** Which inputs a request carries (or a canvas node has wired). */
2050
+ interface Model3dWired {
2051
+ prompt: boolean;
2052
+ image: boolean;
2053
+ back: boolean;
2054
+ left: boolean;
2055
+ right: boolean;
2056
+ /** The fifth photo (`views.top`); only `unordered` rows read it. */
2057
+ top?: boolean;
2058
+ }
2059
+ /**
2060
+ * The image slots the fal adapter's request mapping (`model3dCall`) fills for each kind of
2061
+ * views, in the order it sends them. A row's `maxImages` may not exceed its kind's count.
2062
+ */
2063
+ declare const MODEL3D_IMAGE_SLOTS: {
2064
+ readonly none: readonly ["image"];
2065
+ readonly named: readonly ["image", "back", "left", "right"];
2066
+ readonly ordered: readonly ["image", "left", "back", "right"];
2067
+ readonly unordered: readonly ["image", "back", "left", "right", "top"];
2068
+ };
2069
+ type Model3dInputRefusal = "model3d_needs_image" | "model3d_needs_prompt" | "model3d_needs_input" | "model3d_views_need_image" | "model3d_views_out_of_order";
2070
+ /** Why a row cannot run with these inputs, or null when it can. */
2071
+ declare function model3dInputRefusal(spec: Model3dConstraints, wired: Model3dWired): Model3dInputRefusal | null;
2072
+ /** Whether the row's provider takes this seed: a non-negative integer up to its `seedMax`. */
2073
+ declare function model3dSeedFits(spec: Model3dConstraints, seed: number): boolean;
2074
+ /** The texture a request gets: its own when the row offers it, else the row's default. */
2075
+ declare function model3dTexture(spec: Model3dConstraints, requested: Model3dTexture | undefined): Model3dTexture;
2076
+ /** The resolution a request gets: its own when the row offers it, else the row's default. */
2077
+ declare function model3dResolution(spec: Model3dConstraints, requested: string | undefined): string | undefined;
2078
+ /** The options a request sets that change its price. */
2079
+ interface Model3dPricedOptions {
2080
+ texture?: Model3dTexture;
2081
+ pbr?: boolean;
2082
+ resolution?: string;
2083
+ }
2084
+ /**
2085
+ * What the request carries that changes its price: an image (Tripo prices text lower)
2086
+ * and side views (Hunyuan adds for them). A quote that cannot tell passes both true.
2087
+ */
2088
+ interface Model3dPricedInputs {
2089
+ image: boolean;
2090
+ views: boolean;
2091
+ }
2092
+ /** The pro-backend credit_pricing_flat key one request bills under. */
2093
+ declare function model3dPricingSku(row: CatalogModel, options: Model3dPricedOptions, inputs: Model3dPricedInputs): string;
2094
+ /** Every SKU a row can bill under; pro-backend needs a price for each. */
2095
+ declare function model3dSkus(row: CatalogModel): string[];
2096
+
2097
+ /** The fal path and body for one request. */
2098
+ interface Model3dCall {
2099
+ endpoint: string;
2100
+ input: JsonObject;
2101
+ }
2102
+ /** The fal path and body for one request, by the row's family. Pure; exported for tests. */
2103
+ declare function model3dCall(row: CatalogModel, spec: Model3dConstraints, req: Model3dRequest): Model3dCall;
2104
+
1476
2105
  /**
1477
2106
  * All adapters registered. Keys default to process.env (pro = bare names,
1478
2107
  * enterprise = ENTERPRISE_ prefix, sloosh = SLOOSH_ prefix) when `keys` is omitted.
@@ -1508,4 +2137,4 @@ declare function describeThrown(cause: unknown): ThrownErrorInfo;
1508
2137
  /** Add the AI SDK `GeneratedFile` accessors to adapter image bytes. base64 is computed on first read. */
1509
2138
  declare function toGeneratedImage(image: ImageBytes): GeneratedImage;
1510
2139
 
1511
- export { ADAPTER_IDS, ADAPTER_KEYS, ARRAY_INPUT_SPEC_KEYS, AUDIO_INPUT_SPEC_KEYS, type Adapter, type AdapterContext, type AdapterEndpoints, type AdapterId, type AdapterRegistry, type AiTextProviderOptions, type ArrayInputSpecKey, type AspectRatio, type AudioOutput, type AudioRequest, type AudioResult, type CallContext, Catalog, type CatalogAuth, type CatalogCache, type CatalogCapabilities, type CatalogDisplay, type CatalogEnvelope, type CatalogModel, CatalogModelSchema, CatalogModelSchemaBase, type CatalogOrigin, CatalogSchema, type CatalogSource, type CatalogTextModel, DEFAULT_ADAPTERS, type DataOnlyRow, type DataOnlyVerdict, type DefaultObjectOutput, type Exposure, ExposureSchema, type FalWebhookBody, type GeneratedImage, IMAGE_INPUT_SPEC_KEYS, INPUT_SPEC_SUPPORTS_KEYS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type InputSpec, type InputSpecDimensions, type InputSpecIssue, type InputSpecKey, InputSpecSchema, type JsonObject, JsonObjectSchema, type JsonPrimitive, type JsonValue, JsonValueSchema, type KeyTier, type LanguageModelHandle, type Lifecycle, type LiveCatalogState, MODELS, type MediaPart, type MediaRef, type ModelConstraints, type ModelKit, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, type ModelkitGenerateObjectOptions, type ModelkitGenerateTextOptions, type ModelkitStreamObjectOptions, type ModelkitStreamTextOptions, type ObjectOutput, type ObjectResult, type OnUnsupported, type OutputFormat, type PricingKind, type PrimeCatalogResult, type PromptConventions, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type QuarantineResult, type ReferenceLimits, type ReferenceSyntax, type RequiredInput, type RequiredKeyName, type ResolveResult, type Routing, SURFACES, type SupportedOption, type Surface, SurfaceSchema, type TextMethods, type TextModelInstance, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_INPUT_SPEC_KEYS, VIDEO_TOOL_MODELS, type VideoCallJob, type VideoCallOptions, type VideoJob, type VideoModel, type VideoRequest, type VideoResolution, VideoResolutionSchema, type VideoResult, type VideoSecondsLimits, type VideoToolCallContext, type VideoToolConstraints, type VideoToolKind, type VideoToolOutputFormat, type VideoToolOutputSpec, type VideoToolPlan, type VideoToolRequest, type VideoToolResult, type VideoToolSource, type VideoToolStatus, type VideoToolSubmission, type Warning, adapterServesType, aiSdkTextAdapter, arkAdapter, aspectRatioToSize, classifyHttpError, compareCatalogOrder, createDefaultModelKit, createModelKit, dataOnlyCapable, describe, describeThrown, generateImage as experimental_generateImage, falAdapter, falWebhookBodySchema, fileCatalogCache, generateAudio, generateImage, generateObject, generateText, generateVideo, googleGenaiAdapter, googleImageAdapter, hasAwsCredentials, higgsfieldAdapter, isArrayInputSpecKey, isInputSpecKey, isListed, isListedOn, isModelKitError, keysFromEnv, languageModel, liveCatalog, liveState, mergeTextProviderOptions, missingTierKeys, nearestAspectRatio, normalizeExposure, openaiImageAdapter, passthroughTextModel, planVideoTool, pollUntil, prepareMediaPart, primeCatalog, prodiaAdapter, readErrorBody, replicateAdapter, resetLiveCatalog, resolutionTier, resolveAudioOptions, resolveImageOptions, resolveKeys, resolveVideoOptions, shouldRetry, sleep, sortCatalogRows, streamObject, streamText, textUsageEvent, toGeneratedImage, validateInputSpec, videoLengthViolation, videoToolConstraints, withRetry, xaiVideoAdapter };
2140
+ export { ADAPTER_IDS, ADAPTER_KEYS, ARRAY_INPUT_SPEC_KEYS, AUDIO_INPUT_SPEC_KEYS, type Adapter, type AdapterContext, type AdapterEndpoints, type AdapterId, type AdapterRegistry, type AiTextProviderOptions, type ArrayInputSpecKey, type AspectRatio, type AudioNodeMethods, type AudioOutput, type AudioRequest, type AudioResult, type CallContext, Catalog, type CatalogAuth, type CatalogCache, type CatalogCapabilities, type CatalogDisplay, type CatalogEnvelope, type CatalogModel, CatalogModelSchema, CatalogModelSchemaBase, type CatalogOrigin, CatalogSchema, type CatalogSource, type CatalogTextModel, DEFAULT_ADAPTERS, type DataOnlyRow, type DataOnlyVerdict, type DefaultObjectOutput, type DubbingOutcome, type DubbingRequest, type DubbingResult, type Exposure, ExposureSchema, type FalWebhookBody, type GeneratedImage, IMAGE_INPUT_SPEC_KEYS, INPUT_SPEC_SUPPORTS_KEYS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type InputSpec, type InputSpecDimensions, type InputSpecIssue, type InputSpecKey, InputSpecSchema, type JsonObject, JsonObjectSchema, type JsonPrimitive, type JsonValue, JsonValueSchema, type KeyTier, type LanguageModelHandle, type LanguageOption, type Lifecycle, type LipsyncRequest, type LipsyncResult, type LiveCatalogState, MODEL3D_IMAGE_SLOTS, MODEL3D_MODELS, MODELS, type MaskBox, type MaskPoint, type MediaJobCallContext, type MediaNodeDefaults, type MediaOutput, type MediaPart, type MediaRef, type Model3dCall, type Model3dConstraints, type Model3dEndpoints, type Model3dFamily, type Model3dInputRefusal, type Model3dPricedInputs, type Model3dPricedOptions, type Model3dRequest, type Model3dResult, type Model3dStatus, type Model3dSubmission, type Model3dTexture, type Model3dViews, type Model3dWired, type ModelConstraints, type ModelKit, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, type ModelkitGenerateObjectOptions, type ModelkitGenerateTextOptions, type ModelkitStreamObjectOptions, type ModelkitStreamTextOptions, type ObjectOutput, type ObjectResult, type OnUnsupported, type OutputFormat, type PricingKind, type PrimeCatalogResult, type PromptConventions, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type QuarantineResult, type ReferenceLimits, type ReferenceSyntax, type RequiredInput, type RequiredKeyName, type ResolveResult, type Routing, SURFACES, type SpeechRequest, type SubtitleOptions, type SubtitleTextStyle, type SupportedOption, type Surface, SurfaceSchema, type TextMethods, type TextModelInstance, type TranscriptWord, type TranscriptionRequest, type TranscriptionResult, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_INPUT_SPEC_KEYS, VIDEO_TOOL_MODELS, type VideoCallJob, type VideoCallOptions, type VideoJob, type VideoModel, type VideoRequest, type VideoResolution, VideoResolutionSchema, type VideoResult, type VideoSecondsLimits, type VideoToolCallContext, type VideoToolConstraints, type VideoToolKind, type VideoToolOutputFormat, type VideoToolOutputSpec, type VideoToolPlan, type VideoToolRequest, type VideoToolResult, type VideoToolSource, type VideoToolStatus, type VideoToolSubmission, type VoiceChangeRequest, type VoiceGender, type VoiceOption, type Warning, adapterServesType, aiSdkTextAdapter, arkAdapter, aspectRatioToSize, classifyHttpError, compareCatalogOrder, createDefaultModelKit, createModelKit, dataOnlyCapable, describe, describeThrown, generateImage as experimental_generateImage, falAdapter, falWebhookBodySchema, fileCatalogCache, generateAudio, generateImage, generateObject, generateText, generateVideo, googleGenaiAdapter, googleImageAdapter, hasAwsCredentials, higgsfieldAdapter, isArrayInputSpecKey, isInputSpecKey, isListed, isListedOn, isModelKitError, keysFromEnv, languageModel, liveCatalog, liveState, mergeTextProviderOptions, missingTierKeys, model3dCall, model3dConstraints, model3dInputRefusal, model3dPricingSku, model3dResolution, model3dSeedFits, model3dSkus, model3dTexture, nearestAspectRatio, normalizeExposure, openaiImageAdapter, passthroughTextModel, planVideoTool, pollUntil, prepareMediaPart, primeCatalog, prodiaAdapter, readErrorBody, replicateAdapter, resetLiveCatalog, resolutionTier, resolveAudioOptions, resolveDubbingOptions, resolveImageOptions, resolveKeys, resolveLipsyncOptions, resolveSpeechOptions, resolveTranscriptionOptions, resolveVideoOptions, resolveVoiceChangeOptions, shouldRetry, sleep, sortCatalogRows, streamObject, streamText, textUsageEvent, toGeneratedImage, validateInputSpec, videoLengthViolation, videoToolConstraints, withRetry, xaiVideoAdapter };