@howells/motif-sdk 7.1.0 → 7.3.0

package/dist/registry.js

@@ -26,6 +26,25 @@ const FAL_PRESET_SIZES = {
 		width: 1024
 	}
 };
+// src/errors.ts
+/** `MotifError` and the fal HTTP error mapping. */
+var MotifError = class extends Error {
+	status;
+	code;
+	/** fal's request-correlation id (from the `x-fal-request-id` header or the
+	* error body). Ties a failure back to fal's dashboard/support. */
+	requestId;
+	/** Structured context for the failure, e.g. the refused field. */
+	details;
+	constructor(message, status, code, requestId, details) {
+		super(message);
+		this.name = "MotifError";
+		this.status = status;
+		this.code = code;
+		this.requestId = requestId;
+		this.details = details;
+	}
+};
 // src/models.ts
 const AA_IMAGE_LEADERBOARD_SNAPSHOT = "2026-10-07";
 const AA_IMAGE_SOURCES = ["https://artificialanalysis.ai/image/leaderboard/text-to-image", "https://artificialanalysis.ai/image/leaderboard/editing"];
@@ -72,6 +91,8 @@ const MODELS = {
 		maskImageField: "mask_url",
 		supportsMarkupImage: true,
 		autoEditSize: true,
+		maxCount: 10,
+		singleImageFormats: ["svg"],
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportedOutputFormats: [
@@ -96,7 +117,7 @@ const MODELS = {
 			"xhigh",
 			"max"
 		],
-		supportsResolution: false,
+		supportsResolution: true,
 		supportsSyncMode: true,
 		type: "generation",
 		useQueue: true
@@ -139,6 +160,8 @@ const MODELS = {
 		maskImageField: "mask_url",
 		supportsMarkupImage: true,
 		autoEditSize: true,
+		maxCount: 10,
+		singleImageFormats: ["svg"],
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportedOutputFormats: [
@@ -163,7 +186,7 @@ const MODELS = {
 			"xhigh",
 			"max"
 		],
-		supportsResolution: false,
+		supportsResolution: true,
 		supportsSyncMode: true,
 		type: "generation",
 		useQueue: true
@@ -210,6 +233,12 @@ const MODELS = {
 		pricePerImageUsd: .133,
 		pricing: "$0.133",
 		sizeMode: "gpt_size",
+		supportedAspects: [
+			"auto",
+			"1:1",
+			"3:2",
+			"2:3"
+		],
 		supportsAspect: false,
 		supportsBackground: true,
 		streaming: {
@@ -218,6 +247,7 @@ const MODELS = {
 		},
 		supportsEdit: true,
 		supportsMaskImage: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsQuality: true,
@@ -259,6 +289,7 @@ const MODELS = {
 		supportsAspect: true,
 		supportsEdit: true,
 		supportsLimitGenerations: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: true,
@@ -304,6 +335,7 @@ const MODELS = {
 		],
 		supportsAspect: true,
 		supportsEdit: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: false,
@@ -351,6 +383,7 @@ const MODELS = {
 		supportsEdit: true,
 		supportsGoogleSearch: true,
 		supportsLimitGenerations: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: true,
@@ -425,6 +458,7 @@ const MODELS = {
 		supportsEdit: true,
 		supportsGoogleSearch: true,
 		supportsLimitGenerations: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: true,
@@ -471,6 +505,7 @@ const MODELS = {
 		supportsAspect: true,
 		supportsResolution: false,
 		supportsEdit: true,
+		maxCount: 6,
 		supportsNumImages: true,
 		supportsSeed: true,
 		supportsSyncMode: true,
@@ -512,6 +547,7 @@ const MODELS = {
 		supportsAspect: true,
 		supportsResolution: false,
 		supportsEdit: true,
+		maxCount: 6,
 		supportsNumImages: true,
 		supportsSeed: true,
 		supportsSyncMode: true,
@@ -660,6 +696,7 @@ const MODELS = {
 		supportsAspect: true,
 		supportsEdit: false,
 		supportsGuidanceScale: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: false,
@@ -700,6 +737,7 @@ const MODELS = {
 		supportsAspect: true,
 		supportsResolution: false,
 		supportsEdit: false,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsRenderingSpeed: true,
 		supportsSeed: true,
@@ -745,6 +783,7 @@ const MODELS = {
 			unit: "images",
 			unitPrice: .02
 		},
+		lowercaseResolution: true,
 		maxReferenceImages: 3,
 		name: "Grok Imagine Image",
 		pricePerImageUsd: .02,
@@ -762,6 +801,7 @@ const MODELS = {
 		supportedResolutions: ["1K", "2K"],
 		supportsAspect: true,
 		supportsEdit: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: true,
@@ -812,6 +852,7 @@ const MODELS = {
 		supportsAspect: true,
 		supportsEdit: true,
 		supportsNegativePrompt: true,
+		maxCount: 6,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: false,
@@ -864,6 +905,7 @@ const MODELS = {
 		],
 		supportsAspect: true,
 		supportsEdit: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: false,
@@ -893,6 +935,7 @@ const MODELS = {
 		supportsAspect: true,
 		supportsEdit: true,
 		supportsLimitGenerations: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: false,
@@ -917,6 +960,7 @@ const MODELS = {
 		pricePerImageUsd: .06,
 		pricing: "$0.03 TURBO / $0.06 BALANCED / $0.09 QUALITY",
 		sizeMode: "aspect_ratio",
+		fixedOutputFormat: "png",
 		supportedAspects: [
 			"16:9",
 			"9:16",
@@ -932,6 +976,7 @@ const MODELS = {
 		supportsEdit: false,
 		supportsExpandPrompt: true,
 		supportsNegativePrompt: true,
+		maxCount: 8,
 		supportsNumImages: true,
 		supportsRenderingSpeed: true,
 		supportsResolution: false,
@@ -990,6 +1035,7 @@ const MODELS = {
 			unit: "images",
 			unitPrice: .06
 		},
+		lowercaseResolution: true,
 		maxReferenceImages: 3,
 		name: "Grok Imagine Image 2.0",
 		pricePerImageUsd: .06,
@@ -1007,6 +1053,7 @@ const MODELS = {
 		supportedResolutions: ["1K", "2K"],
 		supportsAspect: true,
 		supportsEdit: true,
+		maxCount: 10,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: true,
@@ -1049,6 +1096,7 @@ const MODELS = {
 		],
 		supportsAspect: true,
 		supportsEdit: true,
+		maxCount: 10,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: false,
@@ -1104,6 +1152,7 @@ const MODELS = {
 			unit: "images",
 			unitPrice: .05
 		},
+		lowercaseResolution: true,
 		maxReferenceImages: 3,
 		name: "Grok Imagine Image Quality",
 		pricePerImageUsd: .05,
@@ -1121,6 +1170,7 @@ const MODELS = {
 		supportedResolutions: ["1K", "2K"],
 		supportsAspect: true,
 		supportsEdit: true,
+		maxCount: 4,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
 		supportsResolution: true,
@@ -1129,40 +1179,79 @@ const MODELS = {
 	},
 	kling: {
 		endpoint: "fal-ai/kling-video/v3/pro/image-to-video",
+		generatesAudio: true,
 		name: "Kling v3 Pro",
+		outputKeys: ["video"],
+		price: {
+			audioUsd: .168,
+			kind: "output-second",
+			usd: .112
+		},
 		pricing: "$0.11/sec",
 		sizeMode: "none",
+		startFrameField: "start_image_url",
 		supportsAspect: false,
 		supportsEdit: false,
 		supportsNumImages: false,
 		supportsResolution: false,
-		type: "video"
+		type: "video",
+		useQueue: true
 	},
 	"kling-turbo": {
 		endpoint: "fal-ai/kling-video/v3/turbo/pro/image-to-video",
 		name: "Kling v3 Turbo Pro",
+		outputKeys: ["video"],
+		price: {
+			kind: "output-second",
+			usd: .14
+		},
 		pricing: "$0.14/sec",
 		sizeMode: "none",
+		startFrameField: "image_url",
 		supportsAspect: false,
 		supportsEdit: false,
 		supportsNumImages: false,
 		supportsResolution: false,
-		type: "video"
+		type: "video",
+		useQueue: true
 	},
 	clarity: {
+		defaultScale: 2,
 		endpoint: "fal-ai/clarity-upscaler",
 		name: "Clarity Upscaler",
+		outputKeys: ["image"],
+		price: {
+			kind: "megapixel",
+			usd: .03
+		},
 		pricing: "$0.03/MP",
+		scaleField: "upscale_factor",
+		scaleRange: {
+			max: 4,
+			min: 1
+		},
 		supportsAspect: false,
 		supportsEdit: false,
 		supportsNumImages: false,
+		supportsPrompt: true,
 		supportsResolution: false,
 		type: "utility"
 	},
 	crystal: {
+		defaultScale: 2,
 		endpoint: "clarityai/crystal-upscaler",
 		name: "Crystal Upscaler",
-		pricing: "$0.02",
+		outputKeys: ["image"],
+		price: {
+			kind: "megapixel",
+			usd: .016
+		},
+		pricing: "$0.016/MP of output",
+		scaleField: "scale_factor",
+		scaleRange: {
+			max: 200,
+			min: 1
+		},
 		supportsAspect: false,
 		supportsEdit: false,
 		supportsNumImages: false,
@@ -1170,55 +1259,27 @@ const MODELS = {
 		type: "utility"
 	}
 };
-[
-	"sunburst",
-	"flare",
-	"gpt",
-	"banana21",
-	"banana2",
-	"banana",
-	"mai-image-2.5",
-	"mai-image-2.5-pro",
-	"seedream5",
-	"qwen3",
-	"banana2-lite",
-	"grok-image-2",
-	"grok-image-quality",
-	"grok-image",
-	"muse-image",
-	"krea3",
-	"flux2-flex",
-	"flux2-pro",
-	"flux2-turbo",
-	"seedream5-lite",
-	"ideogram4",
-	"ideogram3-transparent",
-	"recraft41"
-].filter((id) => MODELS[id]?.supportsEdit === true);
+Object.keys(MODELS).filter((id) => MODELS[id]?.type === "generation");
 // src/cost.ts
 /**
 * Estimate cost based on model and settings. `editImages` is the number of
 * input images on an edit, for Models whose edits cost more than generation.
+* Null for a token-metered Model; throws for an id with no per-image price.
 */
 function estimateCost(model, resolution, numImages = 1, editImages = 0) {
-	const configuredPrice = MODELS[model]?.pricePerImageUsd;
+	const config = MODELS[model];
+	if (config === void 0) throw new MotifError(`Unknown Model: ${model}`, 0, "UNKNOWN_MODEL");
+	const configuredPrice = config.pricePerImageUsd;
 	if (configuredPrice === null) return null;
+	if (configuredPrice === void 0) throw new MotifError(`${model} has no per-image price`, 0);
 	if (model === "mai-image-2.5-pro" && editImages > 0) return .27 * numImages;
 	if (model === "grok-image-2" && editImages > 0) return (resolution === "2K" || resolution === "4K" ? .08 : .06) * numImages + .01 * editImages;
 	if (model === "grok-image-quality") return (resolution === "2K" || resolution === "4K" ? .07 : .05) * numImages + .01 * editImages;
-	if (configuredPrice !== void 0) {
-		if (model === "banana" && resolution === "4K") return configuredPrice * 2 * numImages;
-		if (model === "seedream5" && (resolution === "2K" || resolution === "4K")) return configuredPrice * 2 * numImages;
-		if (model === "grok-image-2" && (resolution === "2K" || resolution === "4K")) return .08 * numImages;
-		if (model === "banana2") return configuredPrice * (resolution === "4K" ? 2 : resolution === "2K" ? 1.5 : resolution === "0.5K" ? .75 : 1) * numImages;
-		return configuredPrice * numImages;
-	}
-	switch (model) {
-		case "gpt": return .133 * numImages;
-		case "clarity": return .03 * numImages;
-		case "crystal": return .02 * numImages;
-		default: return .1 * numImages;
-	}
+	if (model === "banana" && resolution === "4K") return configuredPrice * 2 * numImages;
+	if (model === "seedream5" && (resolution === "2K" || resolution === "4K")) return configuredPrice * 2 * numImages;
+	if (model === "grok-image-2" && (resolution === "2K" || resolution === "4K")) return .08 * numImages;
+	if (model === "banana2") return configuredPrice * (resolution === "4K" ? 2 : resolution === "2K" ? 1.5 : resolution === "0.5K" ? .75 : 1) * numImages;
+	return configuredPrice * numImages;
 }
 // src/tool-registry/analysis.ts
 const ANALYSIS_TOOLS = {
@@ -1596,6 +1657,7 @@ const ASSET_TOOLS = {
 		price: { kind: "metered" },
 		pricing: "$0.02 per unit; fal does not define a unit, and this endpoint returns one mesh per detected object, so no estimate is reported",
 		queued: true,
+		requiredPrompt: "a prompt naming the objects",
 		sourceUrl: "https://fal.ai/models/fal-ai/sam-3/3d-objects",
 		task: "single-image 3D object reconstruction"
 	},
@@ -1631,6 +1693,10 @@ const ASSET_TOOLS = {
 		},
 		pricing: "$0.0025/megapixel",
 		queued: true,
+		scaleRange: {
+			max: 10,
+			min: 1
+		},
 		sourceUrl: "https://fal.ai/models/fal-ai/seedvr/upscale/image/seamless",
 		task: "seamless texture upscaling"
 	},
@@ -1675,7 +1741,6 @@ const BACKGROUND_TOOLS = {
 		defaultOptions: {
 			model: "General Use (Light)",
 			operating_resolution: "1024x1024",
-			output_format: "png",
 			refine_foreground: true
 		},
 		description: "High-resolution dichotomous image segmentation and background removal.",
@@ -1803,7 +1868,6 @@ const BACKGROUND_TOOLS = {
 	},
 	"seedvr-upscale": {
 		category: "restoration",
-		defaultOptions: { output_format: "png" },
 		description: "Diffusion image restoration and upscaling with SeedVR.",
 		endpoint: "fal-ai/seedvr/upscale/image",
 		inputField: "image_url",
@@ -1816,12 +1880,15 @@ const BACKGROUND_TOOLS = {
 		},
 		pricing: "$0.001/megapixel",
 		queued: true,
+		scaleRange: {
+			max: 10,
+			min: 1
+		},
 		sourceUrl: "https://fal.ai/models/fal-ai/seedvr/upscale/image",
 		task: "image restoration and upscaling"
 	},
 	"topaz-adjust": {
 		category: "restoration",
-		defaultOptions: { output_format: "png" },
 		description: "Topaz exposure, white balance, and colour adjustment.",
 		endpoint: "topaz/adjust/image",
 		inputField: "image_url",
@@ -1840,7 +1907,6 @@ const BACKGROUND_TOOLS = {
 	},
 	"topaz-creative": {
 		category: "restoration",
-		defaultOptions: { output_format: "png" },
 		description: "Topaz Bloom upscaling, which reimagines detail rather than preserving it.",
 		endpoint: "topaz/upscale/image/creative",
 		inputField: "image_url",
@@ -1854,12 +1920,15 @@ const BACKGROUND_TOOLS = {
 		},
 		pricing: "$0.08 per started 2 output megapixels, any Bloom model",
 		queued: true,
+		scaleRange: {
+			max: 4,
+			min: 1
+		},
 		sourceUrl: "https://fal.ai/models/topaz/upscale/image/creative",
 		task: "creative image upscaling"
 	},
 	"topaz-denoise": {
 		category: "restoration",
-		defaultOptions: { output_format: "png" },
 		description: "Topaz noise reduction at source resolution.",
 		endpoint: "topaz/denoise/image",
 		inputField: "image_url",
@@ -1878,7 +1947,6 @@ const BACKGROUND_TOOLS = {
 	},
 	"topaz-generative": {
 		category: "restoration",
-		defaultOptions: { output_format: "png" },
 		description: "Topaz Wonder upscaling, which synthesises plausible detail as it enlarges.",
 		endpoint: "topaz/upscale/image/generative",
 		inputField: "image_url",
@@ -1892,6 +1960,10 @@ const BACKGROUND_TOOLS = {
 		},
 		pricing: "$0.08 per started 8 output megapixels at the default Wonder 3; per started 4 with Wonder, Wonder 2, Standard MAX, Redefine or Recover 3",
 		queued: true,
+		scaleRange: {
+			max: 4,
+			min: 1
+		},
 		sourceUrl: "https://fal.ai/models/topaz/upscale/image/generative",
 		task: "generative image upscaling"
 	},
@@ -1899,7 +1971,6 @@ const BACKGROUND_TOOLS = {
 		category: "upscale",
 		defaultOptions: {
 			model: "Standard V2",
-			output_format: "jpeg",
 			upscale_factor: 2
 		},
 		description: "Professional Topaz image enhancement and upscaling.",
@@ -1915,12 +1986,15 @@ const BACKGROUND_TOOLS = {
 		},
 		pricing: "$0.08 for output up to 24MP; $0.16 to 48MP, $0.32 to 96MP, up to $1.36 at 512MP",
 		queued: true,
+		scaleRange: {
+			max: 4,
+			min: 1
+		},
 		sourceUrl: "https://fal.ai/models/fal-ai/topaz/upscale/image",
 		task: "image enhancement"
 	},
 	"topaz-precision": {
 		category: "restoration",
-		defaultOptions: { output_format: "png" },
 		description: "Topaz upscaling that preserves the original detail rather than inventing it.",
 		endpoint: "topaz/upscale/image/precision",
 		inputField: "image_url",
@@ -1934,12 +2008,15 @@ const BACKGROUND_TOOLS = {
 		},
 		pricing: "$0.08 per 24 output megapixels, any precision model",
 		queued: true,
+		scaleRange: {
+			max: 4,
+			min: 1
+		},
 		sourceUrl: "https://fal.ai/models/topaz/upscale/image/precision",
 		task: "faithful image upscaling"
 	},
 	"topaz-restore": {
 		category: "restoration",
-		defaultOptions: { output_format: "png" },
 		description: "Topaz restoration of damaged or degraded photographs at source resolution.",
 		endpoint: "topaz/restore/image",
 		inputField: "image_url",
@@ -1958,7 +2035,6 @@ const BACKGROUND_TOOLS = {
 	},
 	"topaz-sharpen": {
 		category: "restoration",
-		defaultOptions: { output_format: "png" },
 		description: "Topaz deblurring and sharpening at source resolution.",
 		endpoint: "topaz/sharpen/image",
 		inputField: "image_url",
@@ -1979,8 +2055,10 @@ const BACKGROUND_TOOLS = {
 		category: "restoration",
 		description: "Topaz upscaling that preserves the alpha channel end to end.",
 		endpoint: "topaz/upscale/image/transparent",
+		fixedScale: 4,
 		inputField: "image_url",
 		inputKind: "image",
+		keepsAlpha: true,
 		name: "Topaz Transparent Upscale",
 		outputKeys: ["image"],
 		price: {
@@ -2023,6 +2101,10 @@ const BACKGROUND_TOOLS = {
 		},
 		pricing: "$0.01/sec up to 720p output; $0.02 to 1080p, $0.08 above, doubled at 60fps, halved with Gaia 2",
 		queued: true,
+		scaleRange: {
+			max: 4,
+			min: 1
+		},
 		sourceUrl: "https://fal.ai/models/fal-ai/topaz/upscale/video",
 		task: "video enhancement"
 	}
@@ -2035,6 +2117,7 @@ const EDITING_TOOLS = {
 		endpoint: "fal-ai/bria/eraser",
 		inputField: "image_url",
 		inputKind: "image",
+		maskField: "mask_url",
 		name: "Bria Eraser",
 		outputKeys: ["image"],
 		price: {
@@ -2067,6 +2150,7 @@ const EDITING_TOOLS = {
 		endpoint: "fal-ai/bria/genfill",
 		inputField: "image_url",
 		inputKind: "image",
+		maskField: "mask_url",
 		name: "Bria GenFill",
 		outputKeys: ["images"],
 		price: {
@@ -2117,6 +2201,7 @@ const EDITING_TOOLS = {
 		endpoint: "fal-ai/iclight-v2",
 		inputField: "image_url",
 		inputKind: "image",
+		maskField: "mask_image_url",
 		name: "IC-Light v2",
 		outputKeys: ["images"],
 		price: {
@@ -2180,6 +2265,7 @@ const EDITING_TOOLS = {
 		category: "erase",
 		description: "Remove whatever falls inside supplied bounding boxes.",
 		endpoint: "fal-ai/object-removal/bbox",
+		fractionBoxes: true,
 		inputField: "image_url",
 		inputKind: "image",
 		name: "Object Removal by Box",
@@ -2198,6 +2284,7 @@ const EDITING_TOOLS = {
 		endpoint: "fal-ai/object-removal/mask",
 		inputField: "image_url",
 		inputKind: "image",
+		maskField: "mask_url",
 		name: "Object Removal by Mask",
 		outputKeys: ["images"],
 		price: {
@@ -2263,7 +2350,6 @@ const EDITING_TOOLS = {
 	},
 	"text-removal": {
 		category: "erase",
-		defaultOptions: { output_format: "png" },
 		description: "Remove all rendered text from an image, rebuilding what sat behind it.",
 		endpoint: "fal-ai/image-editing/text-removal",
 		inputField: "image_url",
@@ -2473,7 +2559,6 @@ const STRUCTURE_TOOLS = {
 		category: "segmentation",
 		defaultOptions: {
 			min_mask_region_area: 100,
-			output_format: "png",
 			points_per_side: 32,
 			pred_iou_thresh: .88,
 			stability_score_thresh: .95
@@ -2497,14 +2582,14 @@ const STRUCTURE_TOOLS = {
 		category: "segmentation",
 		defaultOptions: {
 			apply_mask: true,
-			max_masks: 3,
-			output_format: "png"
+			max_masks: 3
 		},
 		description: "Segment image objects with text, point, or box prompts. SAM 3.1 adds Object Multiplex for faster multi-object tracking.",
 		endpoint: "fal-ai/sam-3-1/image",
 		inputField: "image_url",
 		inputKind: "image",
 		name: "SAM 3.1 Image",
+		needsTarget: true,
 		outputKeys: [
 			"image",
 			"masks",
@@ -2522,15 +2607,13 @@ const STRUCTURE_TOOLS = {
 	},
 	"sam3-1-video": {
 		category: "segmentation",
-		defaultOptions: {
-			apply_mask: true,
-			prompt: "person"
-		},
+		defaultOptions: { apply_mask: true },
 		description: "SAM 3.1 video segmentation with Object Multiplex tracking for multiple objects.",
 		endpoint: "fal-ai/sam-3-1/video",
 		inputField: "video_url",
 		inputKind: "video",
 		name: "SAM 3.1 Video",
+		needsTarget: true,
 		outputKeys: ["video", "boundingbox_frames_zip"],
 		price: {
 			frames: 16,
@@ -2546,14 +2629,14 @@ const STRUCTURE_TOOLS = {
 		category: "segmentation",
 		defaultOptions: {
 			apply_mask: true,
-			max_masks: 3,
-			output_format: "png"
+			max_masks: 3
 		},
 		description: "Segment image objects with text, point, or box prompts.",
 		endpoint: "fal-ai/sam-3/image",
 		inputField: "image_url",
 		inputKind: "image",
 		name: "SAM 3 Image",
+		needsTarget: true,
 		outputKeys: [
 			"image",
 			"masks",
@@ -2580,6 +2663,7 @@ const STRUCTURE_TOOLS = {
 		inputField: "image_url",
 		inputKind: "image",
 		name: "SAM 3 Image RLE",
+		needsTarget: true,
 		outputKeys: [
 			"rle",
 			"scores",
@@ -2599,7 +2683,6 @@ const STRUCTURE_TOOLS = {
 		defaultOptions: {
 			apply_mask: true,
 			detection_threshold: .5,
-			prompt: "person",
 			video_output_type: "X264 (.mp4)"
 		},
 		description: "Segment and track prompted objects across video frames.",
@@ -2607,6 +2690,7 @@ const STRUCTURE_TOOLS = {
 		inputField: "video_url",
 		inputKind: "video",
 		name: "SAM 3 Video",
+		needsTarget: true,
 		outputKeys: ["video", "boundingbox_frames_zip"],
 		price: {
 			frames: 16,
@@ -2622,14 +2706,14 @@ const STRUCTURE_TOOLS = {
 		category: "segmentation",
 		defaultOptions: {
 			apply_mask: true,
-			detection_threshold: .5,
-			prompt: "person"
+			detection_threshold: .5
 		},
 		description: "Track prompted video objects and return RLE mask data.",
 		endpoint: "fal-ai/sam-3/video-rle",
 		inputField: "video_url",
 		inputKind: "video",
 		name: "SAM 3 Video RLE",
+		needsTarget: true,
 		outputKeys: ["video", "boundingbox_frames_zip"],
 		price: {
 			frames: 16,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "7.1.0",
+  "version": "7.3.0",
   "description": "Node SDK for Motif: image, video and 3D Tasks on fal.ai, with Motif choosing the Model.",
   "keywords": [
     "fal",