@howells/motif-sdk 5.2.0 → 5.4.0

package/dist/index.cjs

@@ -556,6 +556,7 @@ const CARRIED_FIELDS = [
 	"video",
 	"prompt",
 	"mask",
+	"markup",
 	"references",
 	"boxes",
 	"margin",
@@ -713,6 +714,7 @@ const FAL_PRICING_CHECKED_AT = "2026-05-12";
 const FAL_PRICING_CHECKED_JUL_2026 = "2026-07-11";
 const FAL_PRICING_CHECKED_AUG_2026 = "2026-08-23";
 const FAL_PRICING_CHECKED_SEP_2026 = "2026-09-16";
+const FAL_PRICING_CHECKED_OCT_2026 = "2026-10-29";
 const MODELS = {
 	flare: {
 		benchmark: {
@@ -728,7 +730,7 @@ const MODELS = {
 					rank: 2
 				}
 			},
-			useCase: "Frontier generation and editing, evaluated at max quality"
+			useCase: "Frontier generation and editing at max reasoning effort; scored as GPT Image 2.5 until 2.6 is benchmarked"
 		},
 		defaultQuality: "max",
 		customImageSize: {
@@ -738,11 +740,11 @@ const MODELS = {
 			minPixels: 655360,
 			multipleOf: 16
 		},
-		editEndpoint: "openai/gpt-image-2.5/flare/edit",
-		endpoint: "openai/gpt-image-2.5/flare/text-to-image",
+		editEndpoint: "openai/gpt-image-2.6/flare/edit",
+		endpoint: "openai/gpt-image-2.6/flare/text-to-image",
 		maxReferenceImages: 16,
-		name: "GPT Image 2.5 Flare",
-		pricing: "Token-based: text $5/M input, $1.25/M cached, $10/M output; image $8/M input, $2/M cached, $30/M output",
+		name: "GPT Image 2.6 Flare",
+		pricing: "Token-based: image $8/M input, $2/M cached, $30/M output; text $5/M input, $1.25/M cached",
 		pricePerImageUsd: null,
 		sizeMode: "image_size_enum",
 		supportsAspect: true,
@@ -750,8 +752,23 @@ const MODELS = {
 		supportsEdit: true,
 		supportsMaskImage: true,
 		maskImageField: "mask_url",
+		supportsMarkupImage: true,
+		autoEditSize: true,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
+		supportedOutputFormats: [
+			"jpeg",
+			"png",
+			"webp",
+			"gif",
+			"svg"
+		],
+		supportedEditOutputFormats: [
+			"jpeg",
+			"png",
+			"webp",
+			"gif"
+		],
 		supportsQuality: true,
 		supportedQualities: [
 			"auto",
@@ -780,7 +797,7 @@ const MODELS = {
 					rank: 1
 				}
 			},
-			useCase: "Frontier generation and editing, evaluated at max quality"
+			useCase: "Frontier generation and editing at max reasoning effort; scored as GPT Image 2.5 until 2.6 is benchmarked"
 		},
 		defaultQuality: "max",
 		customImageSize: {
@@ -790,11 +807,11 @@ const MODELS = {
 			minPixels: 655360,
 			multipleOf: 16
 		},
-		editEndpoint: "openai/gpt-image-2.5/sunburst/edit",
-		endpoint: "openai/gpt-image-2.5/sunburst/text-to-image",
+		editEndpoint: "openai/gpt-image-2.6/sunburst/edit",
+		endpoint: "openai/gpt-image-2.6/sunburst/text-to-image",
 		maxReferenceImages: 16,
-		name: "GPT Image 2.5 Sunburst",
-		pricing: "Token-based: text $5/M input, $1.25/M cached, $10/M output; image $8/M input, $2/M cached, $30/M output",
+		name: "GPT Image 2.6 Sunburst",
+		pricing: "Token-based: image $8/M input, $2/M cached, $30/M output; text $5/M input, $1.25/M cached",
 		pricePerImageUsd: null,
 		sizeMode: "image_size_enum",
 		supportsAspect: true,
@@ -802,8 +819,23 @@ const MODELS = {
 		supportsEdit: true,
 		supportsMaskImage: true,
 		maskImageField: "mask_url",
+		supportsMarkupImage: true,
+		autoEditSize: true,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
+		supportedOutputFormats: [
+			"jpeg",
+			"png",
+			"webp",
+			"gif",
+			"svg"
+		],
+		supportedEditOutputFormats: [
+			"jpeg",
+			"png",
+			"webp",
+			"gif"
+		],
 		supportsQuality: true,
 		supportedQualities: [
 			"auto",
@@ -2069,6 +2101,7 @@ const MODELS = {
 			maxPixels: 4194304,
 			minPixels: 262144
 		},
+		editEndpoint: "alibaba/qwen-image-3/edit",
 		endpoint: "alibaba/qwen-image-3/text-to-image",
 		falPricing: {
 			checkedAt: FAL_PRICING_CHECKED_SEP_2026,
@@ -2079,12 +2112,13 @@ const MODELS = {
 			unit: "images",
 			unitPrice: .04
 		},
+		maxReferenceImages: 3,
 		name: "Qwen Image 3",
 		pricePerImageUsd: .04,
 		pricing: "$0.04 (1K) / $0.075 (2K)",
 		sizeMode: "image_size_enum",
 		supportsAspect: true,
-		supportsEdit: false,
+		supportsEdit: true,
 		supportsNegativePrompt: true,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
@@ -2287,6 +2321,120 @@ const MODELS = {
 		supportsSyncMode: true,
 		type: "generation"
 	},
+	"muse-image": {
+		benchmark: { useCase: "Low-cost generation and multi-reference editing; Arena #8 generation / #10 editing, 2026-10-29" },
+		editEndpoint: "meta/muse-image/edit",
+		endpoint: "meta/muse-image/text-to-image",
+		falPricing: {
+			checkedAt: FAL_PRICING_CHECKED_OCT_2026,
+			currency: "USD",
+			endpointId: "meta/muse-image/text-to-image",
+			estimatedCostPerImageUsd: .01,
+			source: "fal-pricing-api",
+			unit: "images",
+			unitPrice: .01
+		},
+		maxReferenceImages: 10,
+		name: "Meta Muse Image",
+		pricePerImageUsd: .01,
+		pricing: "$0.01",
+		sizeMode: "aspect_ratio",
+		supportedAspects: [
+			"1:1",
+			"4:3",
+			"3:4",
+			"16:9",
+			"9:16",
+			"3:2",
+			"2:3",
+			"4:5",
+			"5:4",
+			"21:9",
+			"4:1",
+			"1:4",
+			"8:1",
+			"1:8"
+		],
+		supportsAspect: true,
+		supportsEdit: true,
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsResolution: false,
+		supportsSyncMode: true,
+		type: "generation"
+	},
+	krea3: {
+		benchmark: { useCase: "Reference editing with prompt planning. Motif sends fal's defaults (berry, medium reasoning), which Arena has not scored; Arena's 1411 editing score (2026-10-29) is for Ultra, available with --param reasoning_level=ultra" },
+		customImageSize: {
+			maxEdge: 3200,
+			maxPixels: 4220160,
+			minEdge: 256,
+			multipleOf: 16
+		},
+		editEndpoint: "krea/v3/edit",
+		endpoint: "krea/v3/text-to-image",
+		falPricing: {
+			checkedAt: FAL_PRICING_CHECKED_OCT_2026,
+			currency: "USD",
+			endpointId: "krea/v3/text-to-image",
+			estimatedCostPerImageUsd: .025,
+			source: "fal-pricing-api",
+			unit: "megapixels",
+			unitPrice: .025
+		},
+		maxReferenceImages: 8,
+		name: "Krea 3",
+		pricePerImageUsd: .025,
+		pricing: "$0.025/MP (edits also bill each reference)",
+		sizeMode: "image_size_enum",
+		supportedOutputFormats: ["png", "jpeg"],
+		supportsAspect: true,
+		supportsEdit: true,
+		supportsNegativePrompt: true,
+		supportsNumImages: false,
+		supportsOutputFormat: true,
+		supportsResolution: false,
+		supportsSafetyChecker: true,
+		supportsSeed: true,
+		supportsSyncMode: true,
+		type: "generation"
+	},
+	"grok-image-quality": {
+		benchmark: { useCase: "Detailed generation and editing with stronger text rendering; Arena #11 editing, 2026-10-29" },
+		editEndpoint: "xai/grok-imagine-image/quality/edit",
+		endpoint: "xai/grok-imagine-image/quality/text-to-image",
+		falPricing: {
+			checkedAt: FAL_PRICING_CHECKED_OCT_2026,
+			currency: "USD",
+			endpointId: "xai/grok-imagine-image/quality/text-to-image",
+			estimatedCostPerImageUsd: .05,
+			source: "fal-pricing-api",
+			unit: "images",
+			unitPrice: .05
+		},
+		maxReferenceImages: 3,
+		name: "Grok Imagine Image Quality",
+		pricePerImageUsd: .05,
+		pricing: "$0.05 (1K) / $0.07 (2K)",
+		sizeMode: "aspect_ratio",
+		supportedAspects: [
+			"16:9",
+			"4:3",
+			"3:2",
+			"1:1",
+			"2:3",
+			"3:4",
+			"9:16"
+		],
+		supportedResolutions: ["1K", "2K"],
+		supportsAspect: true,
+		supportsEdit: true,
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsResolution: true,
+		supportsSyncMode: true,
+		type: "generation"
+	},
 	kling: {
 		endpoint: "fal-ai/kling-video/v3/pro/image-to-video",
 		name: "Kling v3 Pro",
@@ -2365,7 +2513,10 @@ const GENERATION_MODELS = [
 	"qwen3",
 	"banana2-lite",
 	"grok-image-2",
+	"grok-image-quality",
 	"grok-image",
+	"muse-image",
+	"krea3",
 	"flux2-flex",
 	"flux2-pro",
 	"flux2-turbo",
@@ -2407,6 +2558,7 @@ function estimateCost(model, resolution, numImages = 1, editImages = 0) {
 	if (configuredPrice === null) return null;
 	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" || model === "gemini3") && resolution === "4K") return configuredPrice * 2 * numImages;
 		if (model === "seedream5" && (resolution === "2K" || resolution === "4K")) return configuredPrice * 2 * numImages;
@@ -2552,6 +2704,18 @@ function requestIdFromBody(text) {
 * error can name both what a model does support and which models support the
 * option that was refused.
 */
+const DEFAULT_OUTPUT_FORMATS = [
+	"jpeg",
+	"png",
+	"webp"
+];
+/** The output formats a Model returns, for an edit when `editing` is set.
+* A Model that takes no format returns none it can be asked for. */
+function outputFormatsOf(config, editing) {
+	if (config.supportsOutputFormat !== true) return [];
+	const formats = config.supportedOutputFormats ?? DEFAULT_OUTPUT_FORMATS;
+	return editing ? config.supportedEditOutputFormats ?? formats : formats;
+}
 /** Generation options a model can refuse, with the registry test for each. */
 const OPTION_CAPABILITIES = {
 	aspect: (config) => (config.sizeMode ?? "aspect_ratio") !== "none",
@@ -2567,6 +2731,7 @@ const OPTION_CAPABILITIES = {
 	imageSize: (config) => config.sizeMode === "gpt_size" || config.sizeMode === "image_size_enum",
 	inputFidelity: (config) => config.sizeMode === "gpt_size",
 	limitGenerations: (config) => config.supportsLimitGenerations === true,
+	markupImageUrl: (config) => config.supportsMarkupImage === true,
 	maskImageUrl: (config) => config.supportsMaskImage === true,
 	negativePrompt: (config) => config.supportsNegativePrompt === true,
 	numImages: (config) => config.supportsNumImages,
@@ -2700,6 +2865,9 @@ function validateGenerateOptions(options, config, sizeMode, hasEditImages) {
 	if (options.imagePromptStrength !== void 0 && !hasEditImages) throw new Error("imagePromptStrength requires editImageUrls");
 	if (options.maskImageUrl !== void 0 && config.supportsMaskImage !== true) unsupported(config, "maskImageUrl");
 	if (options.maskImageUrl !== void 0 && !hasEditImages) throw new Error("maskImageUrl requires editImageUrls");
+	if (options.markupImageUrl !== void 0 && config.supportsMarkupImage !== true) unsupported(config, "markupImageUrl");
+	if (options.markupImageUrl !== void 0 && !hasEditImages) throw new Error("markupImageUrl requires editImageUrls");
+	if (options.markupImageUrl !== void 0 && options.maskImageUrl !== void 0) throw new Error("A markup image can't be combined with a mask.");
 	if (options.seed !== void 0 && config.supportsSeed !== true) unsupported(config, "seed");
 	if (options.outputFormat !== void 0 && config.supportsOutputFormat !== true) unsupported(config, "outputFormat");
 	if (options.quality !== void 0 && config.supportsQuality !== true) unsupported(config, "quality");
@@ -2739,7 +2907,7 @@ function validateGenerateOptions(options, config, sizeMode, hasEditImages) {
 * - `none`: no size control (video models)
 */
 function buildGenerateBody(options) {
-	const { prompt, model, creative, aspect = "1:1", resolution = "2K", numImages = 1, background, editImageUrls, enableGoogleSearch, enableSafetyChecker, transparent, inputFidelity, imageSize, imagePromptStrength, limitGenerations, maskImageUrl, seed, outputFormat, quality, negativePrompt, style, syncMode, thinkingLevel, renderingSpeed, guidanceScale, numInferenceSteps, raw, enhancePrompt, safetyTolerance, enableWebSearch, expandPrompt } = options;
+	const { prompt, model, creative, aspect = "1:1", resolution = "2K", numImages = 1, background, editImageUrls, enableGoogleSearch, enableSafetyChecker, transparent, inputFidelity, imageSize, imagePromptStrength, limitGenerations, maskImageUrl, markupImageUrl, seed, outputFormat, quality, negativePrompt, style, syncMode, thinkingLevel, renderingSpeed, guidanceScale, numInferenceSteps, raw, enhancePrompt, safetyTolerance, enableWebSearch, expandPrompt } = options;
 	const config = MODELS[model];
 	if (!config) throw new Error(`Unknown model: ${model}`);
 	let { endpoint } = config;
@@ -2758,11 +2926,11 @@ function buildGenerateBody(options) {
 			body.image_size = normalizedImageSize ?? (hasEditImages && !explicitAspect ? "auto" : aspectToGptSize(aspect));
 			break;
 		case "image_size_enum":
-			body.image_size = normalizedImageSize ?? falImageSizeFor(config, aspect, resolution);
+			body.image_size = normalizedImageSize ?? (config.autoEditSize === true && hasEditImages && !explicitAspect ? "auto" : falImageSizeFor(config, aspect, resolution));
 			break;
 		case "aspect_ratio":
 			if (config.supportsAspect) body.aspect_ratio = aspect;
-			if (config.supportsResolution) body.resolution = model === "grok-image" || model === "grok-image-2" ? resolution.toLowerCase() : resolution;
+			if (config.supportsResolution) body.resolution = model === "grok-image" || model === "grok-image-2" || model === "grok-image-quality" ? resolution.toLowerCase() : resolution;
 	}
 	if (config.supportsQuality === true) body.quality = quality ?? config.defaultQuality ?? "high";
 	if (config.supportsBackground === true && background) body.background = background;
@@ -2771,7 +2939,8 @@ function buildGenerateBody(options) {
 	if (syncMode !== void 0 && config.supportsSyncMode === true) body.sync_mode = syncMode;
 	if (seed !== void 0 && config.supportsSeed === true) body.seed = seed;
 	if (outputFormat && config.supportsOutputFormat === true && transparent !== true) {
-		if (config.supportedOutputFormats && !config.supportedOutputFormats.includes(outputFormat)) throw new Error(`${config.name} supports output formats: ${config.supportedOutputFormats.join(", ")}`);
+		const formats = outputFormatsOf(config, hasEditImages);
+		if (!formats.includes(outputFormat)) throw new Error(`${config.name} ${hasEditImages ? "edits support" : "supports"} output formats: ${formats.join(", ")}`);
 		body.output_format = outputFormat;
 	}
 	if (config.supportsRaw === true && raw !== void 0) body.raw = raw;
@@ -2830,6 +2999,7 @@ function buildGenerateBody(options) {
 		if (inputFidelity) body.input_fidelity = inputFidelity;
 	}
 	if (maskImageUrl !== void 0 && maskImageUrl !== "" && config.supportsMaskImage === true) body[config.maskImageField ?? "mask_image_url"] = maskImageUrl;
+	if (markupImageUrl !== void 0 && config.supportsMarkupImage === true) body.markup_image_url = markupImageUrl;
 	return {
 		body,
 		endpoint
@@ -4418,10 +4588,15 @@ async function getToolResult(exec, job) {
 }
 /** Poll a submitted job to completion and fetch its result. Submits nothing. */
 async function awaitQueuedRequest(exec, job, onProgress) {
+	let logsSeen = 0;
 	for (let attempt = 0; attempt < MAX_POLL_ATTEMPTS; attempt++) {
 		const status = await checkToolStatus(exec, job);
 		if (status.isErr()) return (0, neverthrow.err)(status.error);
-		onProgress?.(status.value.status, status.value.queuePosition);
+		const logs = status.value.logs ?? [];
+		const fresh = logs.slice(logs.length < logsSeen ? 0 : logsSeen);
+		logsSeen = logs.length;
+		if (fresh.length > 0) onProgress?.(status.value.status, status.value.queuePosition, fresh);
+		else onProgress?.(status.value.status, status.value.queuePosition);
 		if (status.value.status === "completed") return (await getToolResult(exec, job)).map((data) => ({
 			data,
 			requestId: job.requestId
@@ -5166,6 +5341,201 @@ function sumCosts(costs) {
 	};
 }
 //#endregion
+//#region src/image-benchmarks.ts
+const BOARDS = {
+	"text-to-image": {
+		sunburst: {
+			elo: 1427,
+			rank: 1,
+			uncertainty: 5,
+			evaluatedModel: "GPT-Image-2.5 Sunburst",
+			preliminary: true,
+			votes: 40323
+		},
+		flare: {
+			elo: 1401,
+			rank: 2,
+			uncertainty: 5,
+			evaluatedModel: "GPT-Image-2.5 Flare",
+			preliminary: true,
+			votes: 39218
+		},
+		gpt2: {
+			elo: 1381,
+			rank: 3,
+			uncertainty: 4,
+			evaluatedModel: "GPT-Image-2 (Medium)",
+			votes: 103385
+		},
+		banana21: {
+			elo: 1325,
+			rank: 5,
+			uncertainty: 9,
+			evaluatedModel: "Nano Banana 2.1",
+			preliminary: true,
+			votes: 5290
+		},
+		"grok-image-2": {
+			elo: 1317,
+			rank: 6,
+			uncertainty: 7,
+			evaluatedModel: "Grok Imagine Image 2.0",
+			preliminary: true,
+			votes: 10902
+		},
+		"muse-image": {
+			elo: 1269,
+			rank: 8,
+			uncertainty: 5,
+			evaluatedModel: "Muse Image (Meta)",
+			votes: 53444
+		},
+		qwen3: {
+			elo: 1254,
+			rank: 9,
+			uncertainty: 6,
+			evaluatedModel: "Qwen-Image-3.0-Pro",
+			votes: 11444
+		},
+		"mai-image-2.5": {
+			elo: 1253,
+			rank: 10,
+			uncertainty: 4,
+			evaluatedModel: "MAI-Image-2.5",
+			votes: 61286
+		},
+		seedream5: {
+			elo: 1250,
+			rank: 11,
+			uncertainty: 4,
+			evaluatedModel: "Seedream 5.0 Pro",
+			votes: 105824
+		},
+		"banana2-lite": {
+			elo: 1249,
+			rank: 12,
+			uncertainty: 6,
+			evaluatedModel: "Nano Banana 2 Lite",
+			votes: 17813
+		},
+		banana: {
+			elo: 1246,
+			rank: 13,
+			uncertainty: 3,
+			evaluatedModel: "Nano Banana Pro (2K)",
+			votes: 188288
+		},
+		gpt: {
+			elo: 1236,
+			rank: 14,
+			uncertainty: 3,
+			evaluatedModel: "GPT-Image-1.5 (High Fidelity)",
+			votes: 174012
+		},
+		ideogram4: {
+			elo: 1200,
+			rank: 15,
+			uncertainty: 4,
+			evaluatedModel: "Ideogram 4.0 (Quality)",
+			votes: 72865
+		},
+		"flux2-flex": {
+			elo: 1156,
+			rank: 17,
+			uncertainty: 3,
+			evaluatedModel: "FLUX.2 [flex]",
+			votes: 156876
+		}
+	},
+	"image-edit-single-image": {
+		sunburst: {
+			elo: 1517,
+			rank: 1,
+			uncertainty: 5,
+			evaluatedModel: "GPT-Image-2.5 Sunburst",
+			preliminary: true
+		},
+		flare: {
+			elo: 1482,
+			rank: 2,
+			uncertainty: 5,
+			evaluatedModel: "GPT-Image-2.5 Flare",
+			preliminary: true
+		},
+		gpt2: {
+			elo: 1460,
+			rank: 4,
+			uncertainty: 3,
+			evaluatedModel: "GPT-Image-2 (Medium)"
+		},
+		"grok-image-2": {
+			elo: 1439,
+			rank: 5,
+			uncertainty: 6,
+			evaluatedModel: "Grok Imagine Image 2.0",
+			preliminary: true
+		},
+		banana21: {
+			elo: 1427,
+			rank: 7,
+			uncertainty: 6,
+			evaluatedModel: "Nano Banana 2.1",
+			preliminary: true
+		},
+		"mai-image-2.5": {
+			elo: 1400,
+			rank: 9,
+			uncertainty: 4,
+			evaluatedModel: "MAI-Image-2.5"
+		},
+		"muse-image": {
+			elo: 1400,
+			rank: 10,
+			uncertainty: 4,
+			evaluatedModel: "Muse Image (Meta)"
+		},
+		"grok-image-quality": {
+			elo: 1391,
+			rank: 11,
+			uncertainty: 6,
+			evaluatedModel: "Grok Imagine Image (Quality, 20260519)"
+		},
+		seedream5: {
+			elo: 1390,
+			rank: 12,
+			uncertainty: 3,
+			evaluatedModel: "Seedream 5.0 Pro"
+		},
+		banana: {
+			elo: 1390,
+			rank: 13,
+			uncertainty: 3,
+			evaluatedModel: "Nano Banana Pro (2K)"
+		},
+		gpt: {
+			elo: 1368,
+			rank: 14,
+			uncertainty: 3,
+			evaluatedModel: "GPT-Image-1.5 (High Fidelity)"
+		}
+	}
+};
+const SOURCES = {
+	"text-to-image": "https://arena.ai/leaderboard/image/text-to-image",
+	"image-edit-single-image": "https://arena.ai/leaderboard/image/image-edit/single-image"
+};
+/** A published score for this route, or null when no matching score was saved. */
+function imageModelBenchmark(model, task) {
+	const score = BOARDS[task][model];
+	if (score === void 0) return null;
+	return {
+		...score,
+		source: SOURCES[task],
+		snapshotDate: "2026-10-29",
+		task
+	};
+}
+//#endregion
 //#region src/tasks.ts
 /**
 * The Task registry: every job Motif does, with the Models that can do it
@@ -5192,7 +5562,195 @@ const TIERS = [
 ];
 const DEFAULT_TIER = "balanced";
 const HAND_RANKED_AT = "2026-09-16";
-const IMAGE_RANKED_AT = "2026-10-07";
+const IMAGE_RANKED_AT = "2026-10-29";
+function withImageBenchmarks(models, task) {
+	return models.map((entry) => ({
+		...entry,
+		benchmark: imageModelBenchmark(entry.model, task)
+	}));
+}
+const GENERATION_MODELS_RANKED = withImageBenchmarks([
+	{
+		model: "sunburst",
+		tier: "quality"
+	},
+	{
+		model: "flare",
+		tier: "quality"
+	},
+	{
+		model: "gpt2",
+		tier: "quality"
+	},
+	{
+		model: "seedream5",
+		tier: "quality"
+	},
+	{
+		model: "gpt",
+		tier: "quality"
+	},
+	{
+		model: "mai-image-2.5-pro",
+		tier: "quality"
+	},
+	{
+		model: "banana21",
+		tier: "balanced"
+	},
+	{
+		model: "grok-image-2",
+		tier: "balanced"
+	},
+	{
+		model: "muse-image",
+		tier: "balanced"
+	},
+	{
+		model: "banana2",
+		tier: "balanced"
+	},
+	{
+		model: "qwen3",
+		tier: "balanced"
+	},
+	{
+		model: "mai-image-2.5",
+		tier: "balanced"
+	},
+	{
+		model: "banana",
+		tier: "balanced"
+	},
+	{
+		model: "ideogram4",
+		tier: "balanced"
+	},
+	{
+		model: "flux2-flex",
+		tier: "balanced"
+	},
+	{
+		model: "recraft41",
+		tier: "balanced"
+	},
+	{
+		model: "flux2-pro",
+		tier: "balanced"
+	},
+	{
+		model: "krea3",
+		tier: "balanced"
+	},
+	{
+		model: "grok-image-quality",
+		tier: "balanced"
+	},
+	{
+		model: "ideogram3-transparent",
+		requires: ["transparency"],
+		supports: ["transparency"],
+		tier: "balanced"
+	},
+	{
+		model: "banana2-lite",
+		tier: "fast"
+	},
+	{
+		model: "grok-image",
+		tier: "fast"
+	},
+	{
+		model: "seedream5-lite",
+		tier: "fast"
+	},
+	{
+		model: "flux2-turbo",
+		tier: "fast"
+	}
+], "text-to-image");
+const EDITING_MODELS_RANKED = withImageBenchmarks([
+	{
+		model: "sunburst",
+		tier: "quality"
+	},
+	{
+		model: "flare",
+		tier: "quality"
+	},
+	{
+		model: "gpt2",
+		tier: "quality"
+	},
+	{
+		model: "seedream5",
+		tier: "quality"
+	},
+	{
+		model: "gpt",
+		tier: "quality"
+	},
+	{
+		model: "mai-image-2.5-pro",
+		tier: "quality"
+	},
+	{
+		model: "grok-image-2",
+		tier: "balanced"
+	},
+	{
+		model: "banana21",
+		tier: "balanced"
+	},
+	{
+		model: "mai-image-2.5",
+		tier: "balanced"
+	},
+	{
+		model: "muse-image",
+		tier: "balanced"
+	},
+	{
+		model: "grok-image-quality",
+		tier: "balanced"
+	},
+	{
+		model: "banana",
+		tier: "balanced"
+	},
+	{
+		model: "banana2",
+		tier: "balanced"
+	},
+	{
+		model: "krea3",
+		tier: "balanced"
+	},
+	{
+		model: "qwen3",
+		tier: "balanced"
+	},
+	{
+		model: "flux2-pro",
+		tier: "balanced"
+	},
+	{
+		model: "flux2-flex",
+		tier: "balanced"
+	},
+	{
+		model: "grok-image",
+		tier: "fast"
+	},
+	{
+		model: "banana2-lite",
+		tier: "fast"
+	},
+	{
+		model: "seedream5-lite",
+		tier: "fast"
+	}
+], "image-edit-single-image");
 /** Every Task with a Model. A Task is absent here until it has at least one Model. */
 const TASKS = {
 	animate: {
@@ -5363,95 +5921,8 @@ const TASKS = {
 		summary: "Remove an object, person, text or clutter from an image and fill the gap."
 	},
 	generate: {
-		basis: "Curated from Artificial Analysis v2, captured 2026-10-07, and Arena 2026-10-06. Sunburst and Flare lead quality at the benchmarked max setting. Nano Banana 2.1 leads balanced on preliminary Arena evidence and lower representative cost; Grok Image 2 and MAI 2.5 are established alternatives. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.",
-		models: [
-			{
-				model: "sunburst",
-				tier: "quality"
-			},
-			{
-				model: "flare",
-				tier: "quality"
-			},
-			{
-				model: "gpt2",
-				tier: "quality"
-			},
-			{
-				model: "gpt",
-				tier: "quality"
-			},
-			{
-				model: "mai-image-2.5-pro",
-				tier: "quality"
-			},
-			{
-				model: "seedream5",
-				tier: "quality"
-			},
-			{
-				model: "banana21",
-				tier: "balanced"
-			},
-			{
-				model: "grok-image-2",
-				tier: "balanced"
-			},
-			{
-				model: "banana2",
-				tier: "balanced"
-			},
-			{
-				model: "mai-image-2.5",
-				tier: "balanced"
-			},
-			{
-				model: "banana",
-				tier: "balanced"
-			},
-			{
-				model: "qwen3",
-				tier: "balanced"
-			},
-			{
-				model: "flux2-flex",
-				tier: "balanced"
-			},
-			{
-				model: "flux2-pro",
-				tier: "balanced"
-			},
-			{
-				model: "ideogram4",
-				tier: "balanced"
-			},
-			{
-				model: "recraft41",
-				tier: "balanced"
-			},
-			{
-				model: "ideogram3-transparent",
-				requires: ["transparency"],
-				supports: ["transparency"],
-				tier: "balanced"
-			},
-			{
-				model: "banana2-lite",
-				tier: "fast"
-			},
-			{
-				model: "grok-image",
-				tier: "fast"
-			},
-			{
-				model: "seedream5-lite",
-				tier: "fast"
-			},
-			{
-				model: "flux2-turbo",
-				tier: "fast"
-			}
-		],
+		basis: "Order follows Arena text-to-image (https://arena.ai/leaderboard/image/text-to-image), read 2026-10-29 (MOT-72). Sunburst and Flare lead quality at the benchmarked max setting. Balanced starts with Nano Banana 2.1 on preliminary Arena evidence, then Grok Image 2 and Muse Image. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Fast keeps Nano Banana 2 Lite, budget Grok and Seedream 5 Lite, and FLUX.2 Turbo. Design, transparency and tuned Look routes are capability exceptions. Generation with References uses the separate editing ranking. Older routes are explicit/pin/Look-only.",
+		models: GENERATION_MODELS_RANKED,
 		notFor: "Variations of an image you already have (vary), or a consistent set of images (series run).",
 		rankedAt: IMAGE_RANKED_AT,
 		rankedFrom: "hand",
@@ -5938,73 +6409,8 @@ const TASKS = {
 		summary: "Trace a raster image to a clean SVG."
 	},
 	vary: {
-		basis: "Curated from Artificial Analysis v2 editing, captured 2026-10-07, and preliminary Arena 2026-10-06 evidence for Nano Banana 2.1. Editing order differs from generation: MAI 2.5 outranks Grok Image 2, and Seedream 5 Pro outranks GPT Image 1.5. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.",
-		models: [
-			{
-				model: "sunburst",
-				tier: "quality"
-			},
-			{
-				model: "flare",
-				tier: "quality"
-			},
-			{
-				model: "gpt2",
-				tier: "quality"
-			},
-			{
-				model: "mai-image-2.5-pro",
-				tier: "quality"
-			},
-			{
-				model: "seedream5",
-				tier: "quality"
-			},
-			{
-				model: "gpt",
-				tier: "quality"
-			},
-			{
-				model: "banana21",
-				tier: "balanced"
-			},
-			{
-				model: "mai-image-2.5",
-				tier: "balanced"
-			},
-			{
-				model: "grok-image-2",
-				tier: "balanced"
-			},
-			{
-				model: "banana2",
-				tier: "balanced"
-			},
-			{
-				model: "banana",
-				tier: "balanced"
-			},
-			{
-				model: "flux2-pro",
-				tier: "balanced"
-			},
-			{
-				model: "flux2-flex",
-				tier: "balanced"
-			},
-			{
-				model: "grok-image",
-				tier: "fast"
-			},
-			{
-				model: "seedream5-lite",
-				tier: "fast"
-			},
-			{
-				model: "banana2-lite",
-				tier: "fast"
-			}
-		],
+		basis: "Order follows Arena image edit, single image (https://arena.ai/leaderboard/image/image-edit/single-image), read 2026-10-29 (MOT-72). Editing order differs from generation: Grok Image 2 leads balanced, ahead of Nano Banana 2.1, and Seedream 5 Pro outranks GPT Image 1.5. Arena scores Krea 3 only at its Ultra setting, which costs $0.27 to $0.35 an edit and ignores the requested size, so krea3, which runs fal's default setting, is ranked as unscored. Models not yet on the board follow the ranked ones in their Tier, in their previous order. The Artificial Analysis v2 snapshot of 2026-10-07 stays as recorded benchmark data. Sunburst and Flare use max quality. vary reuses a previously chosen Model when explicitly supplied, including retained legacy routes.",
+		models: EDITING_MODELS_RANKED,
 		notFor: "A specific change to an image described in words (generate with a reference), or a set of different scenes in one style (series run).",
 		rankedAt: IMAGE_RANKED_AT,
 		rankedFrom: "hand",
@@ -8203,6 +8609,7 @@ function generationProfile(config) {
 	else if (config.transparencyRoute !== void 0) keyed.set("transparency", config.transparencyRoute.apiKeyEnv);
 	if (config.supportsEdit) capabilities.add("references");
 	if (config.supportsMaskImage === true) capabilities.add("mask");
+	if (config.supportsMarkupImage === true) capabilities.add("markup");
 	if ((config.sizeMode ?? "aspect_ratio") !== "none") capabilities.add("aspect");
 	if (config.supportsResolution) capabilities.add("resolution");
 	if (config.supportsNumImages) capabilities.add("count");
@@ -8215,6 +8622,10 @@ function generationProfile(config) {
 		keyedCapabilities: keyed,
 		keys: [FAL_KEY],
 		maxReferences: config.supportsEdit ? config.maxReferenceImages ?? 1 : 0,
+		outputFormats: {
+			edit: outputFormatsOf(config, true),
+			text: outputFormatsOf(config, false)
+		},
 		resolutions: config.supportedResolutions
 	};
 }
@@ -8265,12 +8676,13 @@ function requirements(request) {
 	if (request.transparent === true) needed.push("transparency");
 	if ((request.references ?? 0) > 0) needed.push("references");
 	if (request.mask === true) needed.push("mask");
+	if (request.markup === true) needed.push("markup");
 	if (request.aspect !== void 0) needed.push("aspect");
 	if (request.resolution !== void 0) needed.push("resolution");
 	if ((request.count ?? 1) > 1) needed.push("count");
 	if (request.seed === true) needed.push("seed");
 	if (request.negativePrompt === true) needed.push("negativePrompt");
-	if (request.outputFormat === true) needed.push("outputFormat");
+	if (request.outputFormat !== void 0) needed.push("outputFormat");
 	if (request.rig === true) needed.push("rig");
 	return needed;
 }
@@ -8279,6 +8691,7 @@ function withinLimits(profile, capability, request) {
 	if (capability === "references") return (request.references ?? 0) <= profile.maxReferences;
 	if (capability === "aspect") return accepts(profile.aspects, request.aspect);
 	if (capability === "resolution") return accepts(profile.resolutions, request.resolution);
+	if (capability === "outputFormat") return accepts((request.references ?? 0) > 0 || request.source !== void 0 ? profile.outputFormats?.edit : profile.outputFormats?.text, request.outputFormat);
 	return true;
 }
 function accepts(allowed, value) {
@@ -8333,7 +8746,11 @@ const TIER_ORDER = {
 		"fast"
 	]
 };
-function describeBlock(blockedBy, missingKey, missingInput) {
+function describeBlock(blockedBy, request, missingKey, missingInput) {
+	if (blockedBy === "outputFormat" && request.outputFormat !== void 0) {
+		const editing = (request.references ?? 0) > 0 || request.source !== void 0;
+		return `cannot return ${request.outputFormat}${editing ? " from an edit" : ""}`;
+	}
 	if (missingInput === true) return `needs a ${blockedBy} input`;
 	if (blockedBy === "key") return `needs ${missingKey ?? "a provider key"}`;
 	if (blockedBy === "unknown-model") return "is not a Model for this Task";
@@ -8402,7 +8819,7 @@ function resolveFixed(task, fixed, request, needed, keys) {
 	if (result.ok) return resolved(task, model, tier, chosenBy);
 	const unblockers = chosenBy === "model" ? [] : ["model"];
 	unblockers.push(unblockerFor(result));
-	return unresolved(task, result.blockedBy, unblockers, `${model} (${chosenBy}) ${describeBlock(result.blockedBy, result.missingKey, result.missingInput)}.`, result.missingKey);
+	return unresolved(task, result.blockedBy, unblockers, `${model} (${chosenBy}) ${describeBlock(result.blockedBy, request, result.missingKey, result.missingInput)}.`, result.missingKey);
 }
 /** Old pins and tuned Looks remain usable without recommending predecessors. */
 function legacyEntry(task, model, mode, tier) {
@@ -8577,6 +8994,8 @@ const FAL_IMAGE_PRICE_USD = {
 	"ideogram/v4": MODELS.ideogram4?.pricePerImageUsd ?? .03,
 	"xai/grok-imagine-image": MODELS["grok-image"]?.pricePerImageUsd ?? .02,
 	"xai/grok-imagine-image/v2.0/text-to-image": MODELS["grok-image-2"]?.pricePerImageUsd ?? .06,
+	"xai/grok-imagine-image/quality/text-to-image": MODELS["grok-image-quality"]?.pricePerImageUsd ?? .05,
+	"meta/muse-image/text-to-image": MODELS["muse-image"]?.pricePerImageUsd ?? .01,
 	"microsoft/mai-image-2.5-pro": MODELS["mai-image-2.5-pro"]?.pricePerImageUsd ?? .17,
 	"fal-ai/ideogram/v3/generate-transparent": MODELS["ideogram3-transparent"]?.pricePerImageUsd ?? .06,
 	"alibaba/qwen-image-3/text-to-image": MODELS.qwen3?.pricePerImageUsd ?? .04,
@@ -8634,10 +9053,10 @@ const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
 * Sanity anchor: the Phase 0 benchmark measured gpt-image direct at $0.042
 * (vs $0.133 via fal — full data and methodology on Linear MOT-23).
 *
-* GPT Image 2.5 is token-priced, with no published per-image estimate. Leave
+* GPT Image 2.6 is token-priced, with no published per-image estimate. Leave
 * these models absent so cost remains unknown unless supplied by the provider.
-* https://developers.openai.com/api/docs/models/gpt-image-2.5-flare
-* https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst
+* https://developers.openai.com/api/docs/models/gpt-image-2.6-flare
+* https://developers.openai.com/api/docs/models/gpt-image-2.6-sunburst
 */
 const OPENAI_IMAGE_PRICE_USD = { "gpt-image-1": .042 };
 /**
@@ -9889,11 +10308,12 @@ function taskRequest(task, input) {
 		aspect: input.aspect,
 		count: input.count,
 		look: task === "generate" || task === "vary" ? input.look : void 0,
+		markup: input.markup !== void 0,
 		mask: input.mask !== void 0,
 		mode: input.mode,
 		model: input.model,
 		negativePrompt: input.negativePrompt !== void 0,
-		outputFormat: input.outputFormat !== void 0,
+		outputFormat: input.outputFormat,
 		references,
 		resolution: (task === "generate" || task === "vary") && input.resolution === "2K" ? void 0 : input.resolution,
 		rig: input.rig,
@@ -10004,6 +10424,7 @@ const GENERATION_FIELDS = /* @__PURE__ */ new Set([
 	"aspect",
 	"count",
 	"look",
+	"markup",
 	"mask",
 	"mood",
 	"negativePrompt",
@@ -10014,11 +10435,23 @@ const GENERATION_FIELDS = /* @__PURE__ */ new Set([
 	"seed",
 	"transparent"
 ]);
+const IMAGE_QUALITIES = [
+	"auto",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+];
+function isImageQuality(value) {
+	return IMAGE_QUALITIES.some((level) => level === value);
+}
 /** The TaskInput field behind each option `buildGenerateBody` can refuse. */
 const FIELD_FOR_OPTION = {
 	aspect: "aspect",
 	background: "transparent",
 	"image editing": "references",
+	markupImageUrl: "markup",
 	maskImageUrl: "mask",
 	negativePrompt: "negativePrompt",
 	numImages: "count",
@@ -10058,23 +10491,35 @@ function generationPlan(task, model, config, input) {
 		task
 	}));
 	const editImageUrls = [...task === "vary" && input.image !== void 0 ? [input.image] : [], ...input.references ?? []];
+	if (input.markup !== void 0 && editImageUrls.length === 0) return (0, neverthrow.err)(invalidOption("Markup applies to the image being edited; pass references.", {
+		field: "markup",
+		requires: "references"
+	}));
 	if (input.mask !== void 0 && editImageUrls.length === 0) return (0, neverthrow.err)(invalidOption("A mask applies to a reference image; pass references.", {
 		field: "mask",
 		requires: "references"
 	}));
 	if (input.transparent === true && config.supportsBackground !== true && config.transparencyRoute !== void 0) return openAiPlan(task, model, config.transparencyRoute, input, editImageUrls);
-	if (input.outputFormat !== void 0 && config.supportedOutputFormats !== void 0 && !config.supportedOutputFormats.includes(input.outputFormat)) return (0, neverthrow.err)(cannotCarry("outputFormat", model, task));
+	if (input.outputFormat !== void 0 && !outputFormatsOf(config, editImageUrls.length > 0).includes(input.outputFormat)) return (0, neverthrow.err)(cannotCarry("outputFormat", model, task));
+	const { quality, ...params } = input.params ?? {};
+	const liftQuality = config.supportsQuality === true && quality !== void 0;
+	if (liftQuality && !isImageQuality(quality)) return (0, neverthrow.err)(invalidOption(`params.quality must be one of ${IMAGE_QUALITIES.join(", ")}.`, {
+		field: "params",
+		key: "quality"
+	}));
 	const options = {
 		aspect: input.aspect,
 		background: input.transparent === true ? "transparent" : void 0,
 		creative: creativeOf(input),
 		editImageUrls: editImageUrls.length > 0 ? editImageUrls : void 0,
+		markupImageUrl: input.markup,
 		maskImageUrl: input.mask,
 		model,
 		negativePrompt: input.negativePrompt,
 		numImages: input.count,
 		outputFormat: input.outputFormat,
 		prompt: task === "vary" && (input.prompt ?? "") === "" ? VARY_PROMPT : input.prompt ?? "",
+		quality: liftQuality && isImageQuality(quality) ? quality : void 0,
 		resolution: input.resolution,
 		seed: input.seed
 	};
@@ -10084,7 +10529,7 @@ function generationPlan(task, model, config, input) {
 	} catch (error) {
 		return (0, neverthrow.err)(generationError(error, model, task));
 	}
-	const merged = mergeParams(built.body, input.params, ownedGenerationKeys(input));
+	const merged = mergeParams(built.body, liftQuality ? params : input.params, ownedGenerationKeys(input));
 	if (merged.isErr()) return (0, neverthrow.err)(merged.error);
 	const badSize = checkParamsImageSize(config, model, task, input.params);
 	if (badSize !== void 0) return (0, neverthrow.err)(badSize);
@@ -10702,7 +11147,7 @@ function createMotif(config = {}) {
 			headers
 		};
 		const executor = falRequestExecutor(client.value);
-		return (chosen.queued ? await runRequestQueued(executor, prepared, input.onProgress, input.onSubmitted) : await runRequest(executor, prepared)).map((value) => falOutput(chosen, value));
+		return (chosen.queued || input.onSubmitted !== void 0 ? await runRequestQueued(executor, prepared, input.onProgress, input.onSubmitted) : await runRequest(executor, prepared)).map((value) => falOutput(chosen, value));
 	}
 	async function resume(task, input, requestId) {
 		const planned = plan(task, input);