@shop-os/modelkit 0.5.0 → 0.6.1

package/dist/catalog.d.cts

@@ -68,7 +68,62 @@ type ModelType = "text" | "image" | "video" | "audio"
 /** A face driven by speech (`lipsync`): a `sourceVideo` re-timed or a still `image` animated. */
  | "lipsync"
 /** Speech to text (`transcribe`). */
- | "transcription";
+ | "transcription"
+/** A prompt and/or photos of an object in, a GLB 3D model out. */
+ | "model3d";
+/**
+ * How a `model3d` row's provider API is shaped. The adapter builds the request body and
+ * reads the result per family; everything a caller shows (inputs, views, options) is
+ * data on the row's `constraints.model3d`.
+ */
+type Model3dFamily = "trellis" | "hunyuan" | "tripo" | "rodin" | "meshy" | "hi3d" | "sam";
+/**
+ * How a `model3d` row takes extra views of the object:
+ * - `none`: one image only.
+ * - `unordered`: a list of images in any order (Meshy, Rodin).
+ * - `ordered`: front, left, back, right, contiguous from the front (Tripo).
+ * - `named`: one slot per side (Hunyuan, Hi3D).
+ */
+type Model3dViews = "none" | "unordered" | "ordered" | "named";
+type Model3dTexture = "none" | "standard" | "detailed";
+/** fal paths a `model3d` row calls, by what the request carries. */
+interface Model3dEndpoints {
+    /** A prompt and no image. */
+    text?: string;
+    /** One image. */
+    image?: string;
+    /** More than one image (the main image plus views). */
+    multiImage?: string;
+}
+/** What a `model3d` row takes and offers; see Model3dFamily. */
+interface Model3dConstraints {
+    family: Model3dFamily;
+    endpoints: Model3dEndpoints;
+    /** Takes a text prompt (text-to-3D, or SAM's object name). */
+    text: boolean;
+    /** Needs an image whatever else is sent. */
+    imageRequired: boolean;
+    /** Needs a prompt whatever else is sent (SAM names the object to lift). */
+    promptRequired?: boolean;
+    views: Model3dViews;
+    /** Most images one request takes, the main image included. */
+    maxImages: number;
+    /** Texture choices; empty means the model has no texture switch. */
+    texture: Model3dTexture[];
+    pbr: boolean;
+    /** Takes a texture prompt and a texture image (Meshy). */
+    textureRef: boolean;
+    /** The provider takes a seed (for Meshy, only from a prompt). */
+    seed: boolean;
+    /** Largest seed the provider takes (Rodin: 65535); absent, any non-negative integer. */
+    seedMax?: number;
+    /** A quality or resolution choice the row prices by; absent when it has none. */
+    resolutions?: {
+        label: string;
+        options: string[];
+        default: string;
+    };
+}
 /** What a `video-tool` row does to its source clip. */
 type VideoToolKind = "upscale" | "interpolate" | "hdr" | "bg-remove" | "subtitles";
 /** Container/codec a video-tool row can write. */
@@ -268,6 +323,69 @@ interface VideoToolResult {
     usage: UsageEvent;
     raw?: unknown;
 }
+/** One 3D generation. Image URLs must be public; the provider fetches them. */
+interface Model3dRequest {
+    model: string;
+    prompt?: string;
+    /** The main (front) image. */
+    image?: string;
+    /**
+     * Extra views of the same object; read only by rows whose `views` is not `none`. `top` is a
+     * fifth photo that only `unordered` rows send (all five fit Rodin's `maxImages` 5; Meshy sends
+     * the first 4 set); `named` and `ordered` rows have no slot for it and ignore it.
+     */
+    views?: {
+        back?: string;
+        left?: string;
+        right?: string;
+        top?: string;
+    };
+    /** Rows with `textureRef`. */
+    texturePrompt?: string;
+    textureImage?: string;
+    /** The row's `texture` default when unset; ignored by rows without a texture switch. */
+    texture?: Model3dTexture;
+    /** Rows with `pbr`; only applied to a textured model. */
+    pbr?: boolean;
+    /** One of the row's `resolutions.options`; its default when unset. */
+    resolution?: string;
+    /** Rows with `seed`. */
+    seed?: number;
+}
+/**
+ * A submitted 3D job. Plain JSON so a caller can store it and pass it back to
+ * `model3dStatus` / `model3dResult` / `cancelModel3d` from another process.
+ */
+interface Model3dSubmission {
+    model: string;
+    provider: "fal";
+    /** The fal path the job went to. */
+    endpoint: string;
+    /** The priced option combination (pro-backend credit_pricing_flat model key). */
+    sku: string;
+    requestId: string;
+    statusUrl: string;
+    responseUrl: string;
+    cancelUrl: string;
+    /** Epoch ms when the kit submitted the job; the result's usage `latencyMs` is measured from it. */
+    submittedAt?: number;
+}
+type Model3dStatus = "queued" | "running" | "completed";
+interface Model3dResult {
+    /** The binary glTF the provider made. */
+    glb: {
+        url: string;
+        mime?: string;
+        bytes?: number;
+    };
+    /** The provider's still of the model, when it returns one. */
+    thumbnail?: {
+        url: string;
+    };
+    sku: string;
+    usage: UsageEvent;
+    raw?: unknown;
+}
 interface AudioRequest {
     model: string;
     prompt: string;
@@ -572,6 +690,8 @@ interface ModelConstraints {
     };
     /** What a `video-tool` row accepts. Read it through `videoToolConstraints(row)`. */
     tool?: VideoToolConstraints;
+    /** Required on `model3d` rows. */
+    model3d?: Model3dConstraints;
     /** Whether the output has sound. Read it through `outputAudio(row)`, which tolerates bad data. */
     audio?: AudioOutput;
     /** Prompt conventions. Read them through `promptConventions(row)`, which fills the default. */
@@ -597,7 +717,8 @@ type ProviderOptions = {
         [key: string]: ProviderOptionValue;
     };
 };
-type UsageUnit = "tokens" | "images" | "seconds" | "reported_cost_usd" | "compute_seconds";
+/** `requests`: one call billed at a flat price per request (a 3D job); the usage sink's `REQUESTS`. */
+type UsageUnit = "tokens" | "images" | "seconds" | "reported_cost_usd" | "compute_seconds" | "requests";
 type UsageModality = "TEXT" | "IMAGE" | "VIDEO" | "AUDIO";
 type PricingKind = "token" | "image_size" | "video_per_second" | "flat";
 /** What a model picker shows for a row. Free of any surface-specific ids. */
@@ -938,6 +1059,7 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
         dubbing: "dubbing";
         lipsync: "lipsync";
         transcription: "transcription";
+        model3d: "model3d";
     }>;
     adapter: z.ZodEnum<{
         "ai-sdk-text": "ai-sdk-text";
@@ -1134,6 +1256,46 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
             translationLanguages: z.ZodOptional<z.ZodArray<z.ZodString>>;
             maxSecondsAbove1080p: z.ZodOptional<z.ZodNumber>;
         }, z.core.$loose>>;
+        model3d: z.ZodOptional<z.ZodObject<{
+            family: z.ZodEnum<{
+                trellis: "trellis";
+                hunyuan: "hunyuan";
+                tripo: "tripo";
+                rodin: "rodin";
+                meshy: "meshy";
+                hi3d: "hi3d";
+                sam: "sam";
+            }>;
+            endpoints: z.ZodObject<{
+                text: z.ZodOptional<z.ZodString>;
+                image: z.ZodOptional<z.ZodString>;
+                multiImage: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>;
+            text: z.ZodBoolean;
+            imageRequired: z.ZodBoolean;
+            promptRequired: z.ZodOptional<z.ZodBoolean>;
+            views: z.ZodEnum<{
+                none: "none";
+                unordered: "unordered";
+                ordered: "ordered";
+                named: "named";
+            }>;
+            maxImages: z.ZodNumber;
+            texture: z.ZodArray<z.ZodEnum<{
+                none: "none";
+                standard: "standard";
+                detailed: "detailed";
+            }>>;
+            pbr: z.ZodBoolean;
+            textureRef: z.ZodBoolean;
+            seed: z.ZodBoolean;
+            seedMax: z.ZodOptional<z.ZodNumber>;
+            resolutions: z.ZodOptional<z.ZodObject<{
+                label: z.ZodString;
+                options: z.ZodArray<z.ZodString>;
+                default: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
         audio: z.ZodOptional<z.ZodUnknown>;
         prompt: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$loose>;
@@ -1322,6 +1484,7 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
             seconds: "seconds";
             reported_cost_usd: "reported_cost_usd";
             compute_seconds: "compute_seconds";
+            requests: "requests";
         }>;
         slug: z.ZodOptional<z.ZodString>;
         providerLabel: z.ZodOptional<z.ZodString>;
@@ -1442,6 +1605,64 @@ type VideoToolPlan = {
  */
 declare function planVideoTool(row: CatalogModel, req: Omit<VideoToolRequest, "model">): VideoToolPlan;
 
+/**
+ * 3D generation on fal: the newest model of each 3D family. A request's price depends on
+ * its options (texture, PBR, views, resolution), so each row bills one flat price per
+ * option combination: `model3dSkus(row)` lists them and pro-backend keeps a
+ * credit_pricing_flat row for each.
+ */
+declare const MODEL3D_MODELS: CatalogModel[];
+
+/** A `model3d` row's spec, or undefined for any other row. */
+declare function model3dConstraints(row: CatalogModel): Model3dConstraints | undefined;
+/** Which inputs a request carries (or a canvas node has wired). */
+interface Model3dWired {
+    prompt: boolean;
+    image: boolean;
+    back: boolean;
+    left: boolean;
+    right: boolean;
+    /** The fifth photo (`views.top`); only `unordered` rows read it. */
+    top?: boolean;
+}
+/**
+ * The image slots the fal adapter's request mapping (`model3dCall`) fills for each kind of
+ * views, in the order it sends them. A row's `maxImages` may not exceed its kind's count.
+ */
+declare const MODEL3D_IMAGE_SLOTS: {
+    readonly none: readonly ["image"];
+    readonly named: readonly ["image", "back", "left", "right"];
+    readonly ordered: readonly ["image", "left", "back", "right"];
+    readonly unordered: readonly ["image", "back", "left", "right", "top"];
+};
+type Model3dInputRefusal = "model3d_needs_image" | "model3d_needs_prompt" | "model3d_needs_input" | "model3d_views_need_image" | "model3d_views_out_of_order";
+/** Why a row cannot run with these inputs, or null when it can. */
+declare function model3dInputRefusal(spec: Model3dConstraints, wired: Model3dWired): Model3dInputRefusal | null;
+/** Whether the row's provider takes this seed: a non-negative integer up to its `seedMax`. */
+declare function model3dSeedFits(spec: Model3dConstraints, seed: number): boolean;
+/** The texture a request gets: its own when the row offers it, else the row's default. */
+declare function model3dTexture(spec: Model3dConstraints, requested: Model3dTexture | undefined): Model3dTexture;
+/** The resolution a request gets: its own when the row offers it, else the row's default. */
+declare function model3dResolution(spec: Model3dConstraints, requested: string | undefined): string | undefined;
+/** The options a request sets that change its price. */
+interface Model3dPricedOptions {
+    texture?: Model3dTexture;
+    pbr?: boolean;
+    resolution?: string;
+}
+/**
+ * What the request carries that changes its price: an image (Tripo prices text lower)
+ * and side views (Hunyuan adds for them). A quote that cannot tell passes both true.
+ */
+interface Model3dPricedInputs {
+    image: boolean;
+    views: boolean;
+}
+/** The pro-backend credit_pricing_flat key one request bills under. */
+declare function model3dPricingSku(row: CatalogModel, options: Model3dPricedOptions, inputs: Model3dPricedInputs): string;
+/** Every SKU a row can bill under; pro-backend needs a price for each. */
+declare function model3dSkus(row: CatalogModel): string[];
+
 declare const TEXT_MODELS: CatalogModel[];
 
 declare const OTHER_MODELS: CatalogModel[];
@@ -1596,4 +1817,4 @@ declare class ModelKitError extends Error {
 }
 declare function isModelKitError(err: unknown): err is ModelKitError;
 
-export { ADAPTER_IDS, AUDIO_OUTPUTS, type AdapterEndpoints, type AdapterId, 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 DubbingRequest, type DubbingResult, type Exposure, ExposureSchema, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type KeyTier, type LanguageOption, type Lifecycle, type LipsyncRequest, type LipsyncResult, type LiveCatalogState, MEDIA_METHODS, MEDIA_NODE_MODELS, MODELS, type MaskBox, type MaskPoint, type MediaMethod, type MediaNodeDefaults, type MediaOutput, type MediaPart, type MediaRef, type ModelConstraints, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type PrimeCatalogResult, type PromptConventions, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type QuarantineResult, REFERENCE_SYNTAXES, type ReferenceLimits, type ReferenceSyntax, type RequiredInput, type RequiredKeyName, type ResolveCall, type ResolveResult, type ResolvedCall, type Routing, SURFACES, type SpeechRequest, type SubtitleOptions, type SubtitleTextStyle, type SupportedOption, type Surface, SurfaceSchema, TEXT_MODELS, type TranscriptWord, type TranscriptionRequest, type TranscriptionResult, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, 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, billedAudio, compareCatalogOrder, hasAwsCredentials, isListed, isListedOn, isModelKitError, liveCatalog, liveState, nearestAspectRatio, normalizeExposure, outputAudio, planVideoTool, primeCatalog, promptConventions, resetLiveCatalog, resolutionTier, resolveAudioOptions, resolveDubbingOptions, resolveImageOptions, resolveLipsyncOptions, resolveOptions, resolveSpeechOptions, resolveTranscriptionOptions, resolveVideoOptions, resolveVoiceChangeOptions, sortCatalogRows, videoLengthViolation, videoToolConstraints };
+export { ADAPTER_IDS, AUDIO_OUTPUTS, type AdapterEndpoints, type AdapterId, 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 DubbingRequest, type DubbingResult, type Exposure, ExposureSchema, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type KeyTier, type LanguageOption, type Lifecycle, type LipsyncRequest, type LipsyncResult, type LiveCatalogState, MEDIA_METHODS, MEDIA_NODE_MODELS, MODEL3D_IMAGE_SLOTS, MODEL3D_MODELS, MODELS, type MaskBox, type MaskPoint, type MediaMethod, type MediaNodeDefaults, type MediaOutput, type MediaPart, type MediaRef, 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 ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type PrimeCatalogResult, type PromptConventions, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type QuarantineResult, REFERENCE_SYNTAXES, type ReferenceLimits, type ReferenceSyntax, type RequiredInput, type RequiredKeyName, type ResolveCall, type ResolveResult, type ResolvedCall, type Routing, SURFACES, type SpeechRequest, type SubtitleOptions, type SubtitleTextStyle, type SupportedOption, type Surface, SurfaceSchema, TEXT_MODELS, type TranscriptWord, type TranscriptionRequest, type TranscriptionResult, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, 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, billedAudio, compareCatalogOrder, hasAwsCredentials, isListed, isListedOn, isModelKitError, liveCatalog, liveState, model3dConstraints, model3dInputRefusal, model3dPricingSku, model3dResolution, model3dSeedFits, model3dSkus, model3dTexture, nearestAspectRatio, normalizeExposure, outputAudio, planVideoTool, primeCatalog, promptConventions, resetLiveCatalog, resolutionTier, resolveAudioOptions, resolveDubbingOptions, resolveImageOptions, resolveLipsyncOptions, resolveOptions, resolveSpeechOptions, resolveTranscriptionOptions, resolveVideoOptions, resolveVoiceChangeOptions, sortCatalogRows, videoLengthViolation, videoToolConstraints };

package/dist/catalog.d.ts

@@ -68,7 +68,62 @@ type ModelType = "text" | "image" | "video" | "audio"
 /** A face driven by speech (`lipsync`): a `sourceVideo` re-timed or a still `image` animated. */
  | "lipsync"
 /** Speech to text (`transcribe`). */
- | "transcription";
+ | "transcription"
+/** A prompt and/or photos of an object in, a GLB 3D model out. */
+ | "model3d";
+/**
+ * How a `model3d` row's provider API is shaped. The adapter builds the request body and
+ * reads the result per family; everything a caller shows (inputs, views, options) is
+ * data on the row's `constraints.model3d`.
+ */
+type Model3dFamily = "trellis" | "hunyuan" | "tripo" | "rodin" | "meshy" | "hi3d" | "sam";
+/**
+ * How a `model3d` row takes extra views of the object:
+ * - `none`: one image only.
+ * - `unordered`: a list of images in any order (Meshy, Rodin).
+ * - `ordered`: front, left, back, right, contiguous from the front (Tripo).
+ * - `named`: one slot per side (Hunyuan, Hi3D).
+ */
+type Model3dViews = "none" | "unordered" | "ordered" | "named";
+type Model3dTexture = "none" | "standard" | "detailed";
+/** fal paths a `model3d` row calls, by what the request carries. */
+interface Model3dEndpoints {
+    /** A prompt and no image. */
+    text?: string;
+    /** One image. */
+    image?: string;
+    /** More than one image (the main image plus views). */
+    multiImage?: string;
+}
+/** What a `model3d` row takes and offers; see Model3dFamily. */
+interface Model3dConstraints {
+    family: Model3dFamily;
+    endpoints: Model3dEndpoints;
+    /** Takes a text prompt (text-to-3D, or SAM's object name). */
+    text: boolean;
+    /** Needs an image whatever else is sent. */
+    imageRequired: boolean;
+    /** Needs a prompt whatever else is sent (SAM names the object to lift). */
+    promptRequired?: boolean;
+    views: Model3dViews;
+    /** Most images one request takes, the main image included. */
+    maxImages: number;
+    /** Texture choices; empty means the model has no texture switch. */
+    texture: Model3dTexture[];
+    pbr: boolean;
+    /** Takes a texture prompt and a texture image (Meshy). */
+    textureRef: boolean;
+    /** The provider takes a seed (for Meshy, only from a prompt). */
+    seed: boolean;
+    /** Largest seed the provider takes (Rodin: 65535); absent, any non-negative integer. */
+    seedMax?: number;
+    /** A quality or resolution choice the row prices by; absent when it has none. */
+    resolutions?: {
+        label: string;
+        options: string[];
+        default: string;
+    };
+}
 /** What a `video-tool` row does to its source clip. */
 type VideoToolKind = "upscale" | "interpolate" | "hdr" | "bg-remove" | "subtitles";
 /** Container/codec a video-tool row can write. */
@@ -268,6 +323,69 @@ interface VideoToolResult {
     usage: UsageEvent;
     raw?: unknown;
 }
+/** One 3D generation. Image URLs must be public; the provider fetches them. */
+interface Model3dRequest {
+    model: string;
+    prompt?: string;
+    /** The main (front) image. */
+    image?: string;
+    /**
+     * Extra views of the same object; read only by rows whose `views` is not `none`. `top` is a
+     * fifth photo that only `unordered` rows send (all five fit Rodin's `maxImages` 5; Meshy sends
+     * the first 4 set); `named` and `ordered` rows have no slot for it and ignore it.
+     */
+    views?: {
+        back?: string;
+        left?: string;
+        right?: string;
+        top?: string;
+    };
+    /** Rows with `textureRef`. */
+    texturePrompt?: string;
+    textureImage?: string;
+    /** The row's `texture` default when unset; ignored by rows without a texture switch. */
+    texture?: Model3dTexture;
+    /** Rows with `pbr`; only applied to a textured model. */
+    pbr?: boolean;
+    /** One of the row's `resolutions.options`; its default when unset. */
+    resolution?: string;
+    /** Rows with `seed`. */
+    seed?: number;
+}
+/**
+ * A submitted 3D job. Plain JSON so a caller can store it and pass it back to
+ * `model3dStatus` / `model3dResult` / `cancelModel3d` from another process.
+ */
+interface Model3dSubmission {
+    model: string;
+    provider: "fal";
+    /** The fal path the job went to. */
+    endpoint: string;
+    /** The priced option combination (pro-backend credit_pricing_flat model key). */
+    sku: string;
+    requestId: string;
+    statusUrl: string;
+    responseUrl: string;
+    cancelUrl: string;
+    /** Epoch ms when the kit submitted the job; the result's usage `latencyMs` is measured from it. */
+    submittedAt?: number;
+}
+type Model3dStatus = "queued" | "running" | "completed";
+interface Model3dResult {
+    /** The binary glTF the provider made. */
+    glb: {
+        url: string;
+        mime?: string;
+        bytes?: number;
+    };
+    /** The provider's still of the model, when it returns one. */
+    thumbnail?: {
+        url: string;
+    };
+    sku: string;
+    usage: UsageEvent;
+    raw?: unknown;
+}
 interface AudioRequest {
     model: string;
     prompt: string;
@@ -572,6 +690,8 @@ interface ModelConstraints {
     };
     /** What a `video-tool` row accepts. Read it through `videoToolConstraints(row)`. */
     tool?: VideoToolConstraints;
+    /** Required on `model3d` rows. */
+    model3d?: Model3dConstraints;
     /** Whether the output has sound. Read it through `outputAudio(row)`, which tolerates bad data. */
     audio?: AudioOutput;
     /** Prompt conventions. Read them through `promptConventions(row)`, which fills the default. */
@@ -597,7 +717,8 @@ type ProviderOptions = {
         [key: string]: ProviderOptionValue;
     };
 };
-type UsageUnit = "tokens" | "images" | "seconds" | "reported_cost_usd" | "compute_seconds";
+/** `requests`: one call billed at a flat price per request (a 3D job); the usage sink's `REQUESTS`. */
+type UsageUnit = "tokens" | "images" | "seconds" | "reported_cost_usd" | "compute_seconds" | "requests";
 type UsageModality = "TEXT" | "IMAGE" | "VIDEO" | "AUDIO";
 type PricingKind = "token" | "image_size" | "video_per_second" | "flat";
 /** What a model picker shows for a row. Free of any surface-specific ids. */
@@ -938,6 +1059,7 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
         dubbing: "dubbing";
         lipsync: "lipsync";
         transcription: "transcription";
+        model3d: "model3d";
     }>;
     adapter: z.ZodEnum<{
         "ai-sdk-text": "ai-sdk-text";
@@ -1134,6 +1256,46 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
             translationLanguages: z.ZodOptional<z.ZodArray<z.ZodString>>;
             maxSecondsAbove1080p: z.ZodOptional<z.ZodNumber>;
         }, z.core.$loose>>;
+        model3d: z.ZodOptional<z.ZodObject<{
+            family: z.ZodEnum<{
+                trellis: "trellis";
+                hunyuan: "hunyuan";
+                tripo: "tripo";
+                rodin: "rodin";
+                meshy: "meshy";
+                hi3d: "hi3d";
+                sam: "sam";
+            }>;
+            endpoints: z.ZodObject<{
+                text: z.ZodOptional<z.ZodString>;
+                image: z.ZodOptional<z.ZodString>;
+                multiImage: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>;
+            text: z.ZodBoolean;
+            imageRequired: z.ZodBoolean;
+            promptRequired: z.ZodOptional<z.ZodBoolean>;
+            views: z.ZodEnum<{
+                none: "none";
+                unordered: "unordered";
+                ordered: "ordered";
+                named: "named";
+            }>;
+            maxImages: z.ZodNumber;
+            texture: z.ZodArray<z.ZodEnum<{
+                none: "none";
+                standard: "standard";
+                detailed: "detailed";
+            }>>;
+            pbr: z.ZodBoolean;
+            textureRef: z.ZodBoolean;
+            seed: z.ZodBoolean;
+            seedMax: z.ZodOptional<z.ZodNumber>;
+            resolutions: z.ZodOptional<z.ZodObject<{
+                label: z.ZodString;
+                options: z.ZodArray<z.ZodString>;
+                default: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
         audio: z.ZodOptional<z.ZodUnknown>;
         prompt: z.ZodOptional<z.ZodUnknown>;
     }, z.core.$loose>;
@@ -1322,6 +1484,7 @@ declare const CatalogModelSchemaBase: z.ZodObject<{
             seconds: "seconds";
             reported_cost_usd: "reported_cost_usd";
             compute_seconds: "compute_seconds";
+            requests: "requests";
         }>;
         slug: z.ZodOptional<z.ZodString>;
         providerLabel: z.ZodOptional<z.ZodString>;
@@ -1442,6 +1605,64 @@ type VideoToolPlan = {
  */
 declare function planVideoTool(row: CatalogModel, req: Omit<VideoToolRequest, "model">): VideoToolPlan;
 
+/**
+ * 3D generation on fal: the newest model of each 3D family. A request's price depends on
+ * its options (texture, PBR, views, resolution), so each row bills one flat price per
+ * option combination: `model3dSkus(row)` lists them and pro-backend keeps a
+ * credit_pricing_flat row for each.
+ */
+declare const MODEL3D_MODELS: CatalogModel[];
+
+/** A `model3d` row's spec, or undefined for any other row. */
+declare function model3dConstraints(row: CatalogModel): Model3dConstraints | undefined;
+/** Which inputs a request carries (or a canvas node has wired). */
+interface Model3dWired {
+    prompt: boolean;
+    image: boolean;
+    back: boolean;
+    left: boolean;
+    right: boolean;
+    /** The fifth photo (`views.top`); only `unordered` rows read it. */
+    top?: boolean;
+}
+/**
+ * The image slots the fal adapter's request mapping (`model3dCall`) fills for each kind of
+ * views, in the order it sends them. A row's `maxImages` may not exceed its kind's count.
+ */
+declare const MODEL3D_IMAGE_SLOTS: {
+    readonly none: readonly ["image"];
+    readonly named: readonly ["image", "back", "left", "right"];
+    readonly ordered: readonly ["image", "left", "back", "right"];
+    readonly unordered: readonly ["image", "back", "left", "right", "top"];
+};
+type Model3dInputRefusal = "model3d_needs_image" | "model3d_needs_prompt" | "model3d_needs_input" | "model3d_views_need_image" | "model3d_views_out_of_order";
+/** Why a row cannot run with these inputs, or null when it can. */
+declare function model3dInputRefusal(spec: Model3dConstraints, wired: Model3dWired): Model3dInputRefusal | null;
+/** Whether the row's provider takes this seed: a non-negative integer up to its `seedMax`. */
+declare function model3dSeedFits(spec: Model3dConstraints, seed: number): boolean;
+/** The texture a request gets: its own when the row offers it, else the row's default. */
+declare function model3dTexture(spec: Model3dConstraints, requested: Model3dTexture | undefined): Model3dTexture;
+/** The resolution a request gets: its own when the row offers it, else the row's default. */
+declare function model3dResolution(spec: Model3dConstraints, requested: string | undefined): string | undefined;
+/** The options a request sets that change its price. */
+interface Model3dPricedOptions {
+    texture?: Model3dTexture;
+    pbr?: boolean;
+    resolution?: string;
+}
+/**
+ * What the request carries that changes its price: an image (Tripo prices text lower)
+ * and side views (Hunyuan adds for them). A quote that cannot tell passes both true.
+ */
+interface Model3dPricedInputs {
+    image: boolean;
+    views: boolean;
+}
+/** The pro-backend credit_pricing_flat key one request bills under. */
+declare function model3dPricingSku(row: CatalogModel, options: Model3dPricedOptions, inputs: Model3dPricedInputs): string;
+/** Every SKU a row can bill under; pro-backend needs a price for each. */
+declare function model3dSkus(row: CatalogModel): string[];
+
 declare const TEXT_MODELS: CatalogModel[];
 
 declare const OTHER_MODELS: CatalogModel[];
@@ -1596,4 +1817,4 @@ declare class ModelKitError extends Error {
 }
 declare function isModelKitError(err: unknown): err is ModelKitError;
 
-export { ADAPTER_IDS, AUDIO_OUTPUTS, type AdapterEndpoints, type AdapterId, 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 DubbingRequest, type DubbingResult, type Exposure, ExposureSchema, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type KeyTier, type LanguageOption, type Lifecycle, type LipsyncRequest, type LipsyncResult, type LiveCatalogState, MEDIA_METHODS, MEDIA_NODE_MODELS, MODELS, type MaskBox, type MaskPoint, type MediaMethod, type MediaNodeDefaults, type MediaOutput, type MediaPart, type MediaRef, type ModelConstraints, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type PrimeCatalogResult, type PromptConventions, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type QuarantineResult, REFERENCE_SYNTAXES, type ReferenceLimits, type ReferenceSyntax, type RequiredInput, type RequiredKeyName, type ResolveCall, type ResolveResult, type ResolvedCall, type Routing, SURFACES, type SpeechRequest, type SubtitleOptions, type SubtitleTextStyle, type SupportedOption, type Surface, SurfaceSchema, TEXT_MODELS, type TranscriptWord, type TranscriptionRequest, type TranscriptionResult, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, 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, billedAudio, compareCatalogOrder, hasAwsCredentials, isListed, isListedOn, isModelKitError, liveCatalog, liveState, nearestAspectRatio, normalizeExposure, outputAudio, planVideoTool, primeCatalog, promptConventions, resetLiveCatalog, resolutionTier, resolveAudioOptions, resolveDubbingOptions, resolveImageOptions, resolveLipsyncOptions, resolveOptions, resolveSpeechOptions, resolveTranscriptionOptions, resolveVideoOptions, resolveVoiceChangeOptions, sortCatalogRows, videoLengthViolation, videoToolConstraints };
+export { ADAPTER_IDS, AUDIO_OUTPUTS, type AdapterEndpoints, type AdapterId, 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 DubbingRequest, type DubbingResult, type Exposure, ExposureSchema, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type KeyTier, type LanguageOption, type Lifecycle, type LipsyncRequest, type LipsyncResult, type LiveCatalogState, MEDIA_METHODS, MEDIA_NODE_MODELS, MODEL3D_IMAGE_SLOTS, MODEL3D_MODELS, MODELS, type MaskBox, type MaskPoint, type MediaMethod, type MediaNodeDefaults, type MediaOutput, type MediaPart, type MediaRef, 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 ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type PrimeCatalogResult, type PromptConventions, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type QuarantineResult, REFERENCE_SYNTAXES, type ReferenceLimits, type ReferenceSyntax, type RequiredInput, type RequiredKeyName, type ResolveCall, type ResolveResult, type ResolvedCall, type Routing, SURFACES, type SpeechRequest, type SubtitleOptions, type SubtitleTextStyle, type SupportedOption, type Surface, SurfaceSchema, TEXT_MODELS, type TranscriptWord, type TranscriptionRequest, type TranscriptionResult, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, 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, billedAudio, compareCatalogOrder, hasAwsCredentials, isListed, isListedOn, isModelKitError, liveCatalog, liveState, model3dConstraints, model3dInputRefusal, model3dPricingSku, model3dResolution, model3dSeedFits, model3dSkus, model3dTexture, nearestAspectRatio, normalizeExposure, outputAudio, planVideoTool, primeCatalog, promptConventions, resetLiveCatalog, resolutionTier, resolveAudioOptions, resolveDubbingOptions, resolveImageOptions, resolveLipsyncOptions, resolveOptions, resolveSpeechOptions, resolveTranscriptionOptions, resolveVideoOptions, resolveVoiceChangeOptions, sortCatalogRows, videoLengthViolation, videoToolConstraints };