@howells/motif-sdk 5.1.1 → 5.2.0

package/README.md

@@ -32,6 +32,22 @@ console.log(result.value.model, result.value.files[0]?.url, result.value.cost);
 
 Every Task function returns `Result<TaskOutput, MotifError>` from `neverthrow` and does not throw for fal request failures; check `isErr()` / `isOk()`.
 
+## Curated Models and Tiers
+
+The Task client curates 21 generation Models, with separate rankings for generation and editing. `TASKS.generate` and `TASKS.vary` expose the current choices, Tiers and evidence in `basis` and `rankedAt`. A generation with `references` uses the editing ranking.
+
+| Tier                 | Generation default | Editing default   |
+| -------------------- | ------------------ | ----------------- |
+| `quality`            | Sunburst at `max`  | Sunburst at `max` |
+| `balanced` (default) | Nano Banana 2.1    | Nano Banana 2.1   |
+| `fast`               | Nano Banana 2 Lite | Grok              |
+
+These are the first choices when the request's capabilities and available keys permit them. Explicit Models, Looks and pins take precedence. Selected specialists remain for typography, transparency, control and inexpensive drafts. Archived predecessors remain available through explicit Models, pins and existing Looks, including `flux2-dev` for streaming.
+
+Nano Banana 2.1 (`banana21`) supports up to 14 References and 1K/2K/4K output, with no 0.5K output. Its balanced placement uses preliminary Arena evidence. Sunburst and Flare default to the benchmarked `max` quality on fal; `params: { quality: "high" }` with an explicit `model` overrides it. The direct provider image layer described below has its own adapter capabilities and chooses no Model.
+
+Token-billed Task plans, including Sunburst, Flare, Nano Banana 2.1, Banana Lite and MAI 2.5, report `cost: { usd: null, basis: "unknown" }`; a published representative price is not an exact total. The [curation audit](https://github.com/howells/motif/blob/main/docs/research/image-model-curation-2026-10-07.md) records the current rankings, specialist roles and provider coverage gaps.
+
 Pass `onProgress(status, queuePosition)` to hear fal's queue state while a run waits: `"queued"` with its place in line, then `"processing"`, then `"completed"` (or `"failed"`). Passing it sends the run through fal's queue, since only the queue reports state. Models without streaming report state, not a percentage.
 
 Pass `onSubmitted(requestId)` to hear the request id the moment fal's queue accepts the run, before any wait. Keep it: after a restart, `motif.resume(task, input, requestId)` waits for that same job and returns its output, submitting nothing and so paying nothing twice. Passing `onSubmitted` also queues the run.

package/dist/image.js

@@ -51,7 +51,7 @@ function falHttpError(status, body, requestId) {
 }
 //#endregion
 //#region src/models.ts
-const AA_IMAGE_LEADERBOARD_SNAPSHOT = "2026-08-23";
+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"];
 const FAL_PRICING_CHECKED_AT = "2026-05-12";
 const FAL_PRICING_CHECKED_JUL_2026 = "2026-07-11";
@@ -59,6 +59,22 @@ const FAL_PRICING_CHECKED_AUG_2026 = "2026-08-23";
 const FAL_PRICING_CHECKED_SEP_2026 = "2026-09-16";
 const MODELS = {
 	flare: {
+		benchmark: {
+			artificialAnalysis: {
+				editing: {
+					elo: 1163,
+					rank: 2
+				},
+				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
+				sourceUrls: AA_IMAGE_SOURCES,
+				textToImage: {
+					elo: 1191,
+					rank: 2
+				}
+			},
+			useCase: "Frontier generation and editing, evaluated at max quality"
+		},
+		defaultQuality: "max",
 		customImageSize: {
 			maxEdge: 3840,
 			maxPixels: 8294400,
@@ -95,6 +111,22 @@ const MODELS = {
 		useQueue: true
 	},
 	sunburst: {
+		benchmark: {
+			artificialAnalysis: {
+				editing: {
+					elo: 1183,
+					rank: 1
+				},
+				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
+				sourceUrls: AA_IMAGE_SOURCES,
+				textToImage: {
+					elo: 1198,
+					rank: 1
+				}
+			},
+			useCase: "Frontier generation and editing, evaluated at max quality"
+		},
+		defaultQuality: "max",
 		customImageSize: {
 			maxEdge: 3840,
 			maxPixels: 8294400,
@@ -134,14 +166,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1256,
-					rank: 3
+					elo: 1125,
+					rank: 5
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1369,
-					rank: 1
+					elo: 1172,
+					rank: 3
 				}
 			},
 			speed: {
@@ -154,7 +186,7 @@ const MODELS = {
 				quality: "frontier",
 				speed: "very_slow"
 			},
-			useCase: "Highest-ranked text-to-image quality and transparent PNGs"
+			useCase: "Established frontier generation and transparent PNGs"
 		},
 		customImageSize: {
 			maxEdge: 3840,
@@ -205,14 +237,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1250,
-					rank: 5
+					elo: 1103,
+					rank: 12
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1310,
-					rank: 4
+					elo: 1107,
+					rank: 8
 				}
 			},
 			speed: {
@@ -225,7 +257,7 @@ const MODELS = {
 				quality: "frontier",
 				speed: "slow"
 			},
-			useCase: "Best OpenAI edit quality with transparent PNG support"
+			useCase: "Established OpenAI editor with transparent PNG support"
 		},
 		editEndpoint: "fal-ai/gpt-image-1.5/edit",
 		endpoint: "fal-ai/gpt-image-1.5",
@@ -258,18 +290,103 @@ const MODELS = {
 		supportsSyncMode: true,
 		type: "generation"
 	},
-	banana2: {
+	banana21: {
+		benchmark: { useCase: "Efficient generation and reference editing; Arena #5 generation / #6 editing, preliminary 2026-10-06" },
+		editEndpoint: "google/nano-banana-2.1/edit",
+		endpoint: "google/nano-banana-2.1",
+		maxReferenceImages: 14,
+		name: "Nano Banana 2.1",
+		pricePerImageUsd: null,
+		pricing: "Token-based: input $1.764/M, text/thinking output $8.823/M, image output $35.294/M; ~ $0.040 / $0.059 / $0.134 at 1K / 2K / 4K plus variable usage",
+		sizeMode: "aspect_ratio",
+		supportedAspects: [
+			"auto",
+			"21:9",
+			"16:9",
+			"3:2",
+			"4:3",
+			"5:4",
+			"1:1",
+			"4:5",
+			"3:4",
+			"2:3",
+			"9:16",
+			"4:1",
+			"1:4",
+			"8:1",
+			"1:8"
+		],
+		supportedResolutions: [
+			"1K",
+			"2K",
+			"4K"
+		],
+		supportsAspect: true,
+		supportsEdit: true,
+		supportsLimitGenerations: true,
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsResolution: true,
+		supportsSafetyTolerance: true,
+		supportsSeed: true,
+		supportsSyncMode: true,
+		supportsThinkingLevel: true,
+		supportsWebSearch: true,
+		type: "generation"
+	},
+	"mai-image-2.5": {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1249,
+					elo: 1114,
 					rank: 7
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1320,
-					rank: 3
+					elo: 1104,
+					rank: 10
+				}
+			},
+			useCase: "Strong single-reference editing at a lower price than MAI 2.5 Pro"
+		},
+		editEndpoint: "microsoft/mai-image-2.5/edit",
+		endpoint: "microsoft/mai-image-2.5",
+		maxReferenceImages: 1,
+		name: "MAI Image 2.5",
+		pricePerImageUsd: null,
+		pricing: "Token-based: text input $5/M, image input $8/M; ~$0.05 image output plus input",
+		sizeMode: "aspect_ratio",
+		supportedAspects: [
+			"auto",
+			"1:1",
+			"4:3",
+			"3:4",
+			"16:9",
+			"9:16",
+			"3:2",
+			"2:3"
+		],
+		supportsAspect: true,
+		supportsEdit: true,
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsResolution: false,
+		supportsSyncMode: true,
+		type: "generation"
+	},
+	banana2: {
+		benchmark: {
+			artificialAnalysis: {
+				editing: {
+					elo: 1110,
+					rank: 9
+				},
+				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
+				sourceUrls: AA_IMAGE_SOURCES,
+				textToImage: {
+					elo: 1126,
+					rank: 6
 				}
 			},
 			tiers: {
@@ -277,7 +394,7 @@ const MODELS = {
 				quality: "frontier",
 				speed: "unknown"
 			},
-			useCase: "Best balance of quality, edit support, web search, and cost"
+			useCase: "Previous-generation Gemini workhorse; retains 0.5K output"
 		},
 		editEndpoint: "fal-ai/nano-banana-2/edit",
 		endpoint: "fal-ai/nano-banana-2",
@@ -313,14 +430,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1245,
-					rank: 9
+					elo: 1101,
+					rank: 13
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1297,
-					rank: 6
+					elo: 1102,
+					rank: 11
 				}
 			},
 			speed: {
@@ -385,11 +502,15 @@ const MODELS = {
 	gemini: {
 		benchmark: { artificialAnalysis: {
 			editing: {
-				elo: 1180,
-				rank: 29
+				elo: 987,
+				rank: 50
 			},
 			snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
-			sourceUrls: AA_IMAGE_SOURCES
+			sourceUrls: AA_IMAGE_SOURCES,
+			textToImage: {
+				elo: 985,
+				rank: 60
+			}
 		} },
 		editEndpoint: "fal-ai/gemini-25-flash-image/edit",
 		endpoint: "fal-ai/gemini-25-flash-image",
@@ -430,18 +551,6 @@ const MODELS = {
 		type: "generation"
 	},
 	gemini3: {
-		benchmark: { artificialAnalysis: {
-			editing: {
-				elo: 1245,
-				rank: 9
-			},
-			snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
-			sourceUrls: AA_IMAGE_SOURCES,
-			textToImage: {
-				elo: 1297,
-				rank: 6
-			}
-		} },
 		editEndpoint: "fal-ai/gemini-3-pro-image-preview/edit",
 		endpoint: "fal-ai/gemini-3-pro-image-preview",
 		falPricing: {
@@ -491,14 +600,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1185,
-					rank: 28
+					elo: 1015,
+					rank: 36
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1226,
-					rank: 16
+					elo: 1030,
+					rank: 21
 				}
 			},
 			speed: {
@@ -511,7 +620,7 @@ const MODELS = {
 				quality: "best",
 				speed: "balanced"
 			},
-			useCase: "High-ranked budget generation and large multi-reference edits"
+			useCase: "Legacy budget generation and large multi-reference edits"
 		},
 		customImageSize: {
 			maxPixels: 16777216,
@@ -545,14 +654,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1186,
-					rank: 26
+					elo: 1037,
+					rank: 32
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1203,
-					rank: 32
+					elo: 1022,
+					rank: 26
 				}
 			},
 			speed: {
@@ -598,14 +707,14 @@ const MODELS = {
 	seedream5: {
 		benchmark: { artificialAnalysis: {
 			editing: {
-				elo: 1248,
-				rank: 8
+				elo: 1108,
+				rank: 11
 			},
 			snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 			sourceUrls: AA_IMAGE_SOURCES,
 			textToImage: {
-				elo: 1279,
-				rank: 10
+				elo: 1081,
+				rank: 15
 			}
 		} },
 		customImageSize: {
@@ -640,11 +749,15 @@ const MODELS = {
 	"seedream5-lite": {
 		benchmark: { artificialAnalysis: {
 			editing: {
-				elo: 1169,
-				rank: 32
+				elo: 1057,
+				rank: 24
 			},
 			snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
-			sourceUrls: AA_IMAGE_SOURCES
+			sourceUrls: AA_IMAGE_SOURCES,
+			textToImage: {
+				elo: 1012,
+				rank: 36
+			}
 		} },
 		customImageSize: {
 			maxPixels: 16777216,
@@ -678,14 +791,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1201,
-					rank: 19
+					elo: 997,
+					rank: 49
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1225,
-					rank: 17
+					elo: 1020,
+					rank: 28
 				}
 			},
 			speed: {
@@ -737,14 +850,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1170,
-					rank: 31
+					elo: 1007,
+					rank: 41
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1207,
-					rank: 30
+					elo: 1004,
+					rank: 41
 				}
 			},
 			speed: {
@@ -795,11 +908,15 @@ const MODELS = {
 	"flux2-flex": {
 		benchmark: {
 			artificialAnalysis: {
+				editing: {
+					elo: 1007,
+					rank: 42
+				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1223,
-					rank: 18
+					elo: 1027,
+					rank: 22
 				}
 			},
 			speed: {
@@ -853,8 +970,16 @@ const MODELS = {
 	"flux2-dev": {
 		benchmark: {
 			artificialAnalysis: {
+				editing: {
+					elo: 1e3,
+					rank: 45
+				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
-				sourceUrls: AA_IMAGE_SOURCES
+				sourceUrls: AA_IMAGE_SOURCES,
+				textToImage: {
+					elo: 1e3,
+					rank: 42
+				}
 			},
 			speed: {
 				medianSeconds: 4.6,
@@ -1017,24 +1142,12 @@ const MODELS = {
 	},
 	reve: {
 		benchmark: {
-			artificialAnalysis: {
-				editing: {
-					elo: 1263,
-					rank: 2
-				},
-				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
-				sourceUrls: AA_IMAGE_SOURCES,
-				textToImage: {
-					elo: 1322,
-					rank: 2
-				}
-			},
 			tiers: {
 				price: "premium",
 				quality: "frontier",
 				speed: "unknown"
 			},
-			useCase: "Highest-ranked editor reachable on fal; strong prompt adherence and text rendering"
+			useCase: "Historical Reve route; not currently verified on fal"
 		},
 		editEndpoint: "fal-ai/reve/edit",
 		endpoint: "fal-ai/reve/text-to-image",
@@ -1075,8 +1188,8 @@ const MODELS = {
 			snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 			sourceUrls: AA_IMAGE_SOURCES,
 			textToImage: {
-				elo: 1215,
-				rank: 25
+				elo: 984,
+				rank: 62
 			}
 		} },
 		customImageSize: {},
@@ -1134,8 +1247,8 @@ const MODELS = {
 			snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 			sourceUrls: AA_IMAGE_SOURCES,
 			textToImage: {
-				elo: 1220,
-				rank: 19
+				elo: 1004,
+				rank: 40
 			}
 		} },
 		customImageSize: {
@@ -1173,14 +1286,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1214,
-					rank: 16
+					elo: 1073,
+					rank: 19
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1216,
-					rank: 23
+					elo: 1019,
+					rank: 30
 				}
 			},
 			speed: {
@@ -1233,7 +1346,11 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
-				sourceUrls: AA_IMAGE_SOURCES
+				sourceUrls: AA_IMAGE_SOURCES,
+				textToImage: {
+					elo: 890,
+					rank: 106
+				}
 			},
 			speed: {
 				medianSeconds: 23.3,
@@ -1275,14 +1392,14 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1218,
-					rank: 15
+					elo: 1056,
+					rank: 25
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1272,
-					rank: 11
+					elo: 1075,
+					rank: 16
 				}
 			},
 			tiers: {
@@ -1290,7 +1407,7 @@ const MODELS = {
 				quality: "better",
 				speed: "unknown"
 			},
-			useCase: "Strong quality per dollar - 11th on text-to-image at $30/1k"
+			useCase: "Strong generation with negative-prompt and seed controls"
 		},
 		customImageSize: {
 			maxPixels: 4194304,
@@ -1324,17 +1441,17 @@ const MODELS = {
 		benchmark: {
 			artificialAnalysis: {
 				editing: {
-					elo: 1272,
-					rank: 1
+					elo: 1110,
+					rank: 10
 				},
 				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 				sourceUrls: AA_IMAGE_SOURCES,
 				textToImage: {
-					elo: 1293,
-					rank: 7
+					elo: 1100,
+					rank: 12
 				}
 			},
-			useCase: "Highest-ranked image editor, single reference image"
+			useCase: "Strong single-reference editor; MAI 2.5 ranks higher on the current editing board"
 		},
 		editEndpoint: "microsoft/mai-image-2.5-pro/edit",
 		editImagesField: "image_url",
@@ -1373,20 +1490,26 @@ const MODELS = {
 	},
 	"banana2-lite": {
 		benchmark: { artificialAnalysis: {
+			editing: {
+				elo: 1046,
+				rank: 26
+			},
 			snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
 			sourceUrls: AA_IMAGE_SOURCES,
 			textToImage: {
-				elo: 1289,
-				rank: 8
+				elo: 1095,
+				rank: 13
 			}
 		} },
+		editEndpoint: "google/nano-banana-2-lite/edit",
+		maxReferenceImages: 14,
 		endpoint: "google/nano-banana-2-lite",
 		name: "Nano Banana 2 Lite",
-		pricing: "Token-based: text $0.3125/M input, $1.875/M output; image $0.3125/M input, $37.50/M output; fixed 1K output (~$0.048)",
-		pricePerImageUsd: .048,
+		pricing: "Token-based: text $0.3125/M input, $1.875/M output; image $0.3125/M input, $37.50/M output; fixed 1K output (~$0.042 image output, plus input/thinking)",
+		pricePerImageUsd: null,
 		sizeMode: "aspect_ratio",
 		supportsAspect: true,
-		supportsEdit: false,
+		supportsEdit: true,
 		supportsLimitGenerations: true,
 		supportsNumImages: true,
 		supportsOutputFormat: true,
@@ -1459,6 +1582,21 @@ const MODELS = {
 		type: "generation"
 	},
 	"grok-image-2": {
+		benchmark: {
+			artificialAnalysis: {
+				editing: {
+					elo: 1110,
+					rank: 8
+				},
+				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
+				sourceUrls: AA_IMAGE_SOURCES,
+				textToImage: {
+					elo: 1156,
+					rank: 4
+				}
+			},
+			useCase: "Strong generation and editing with predictable per-image billing"
+		},
 		editEndpoint: "xai/grok-imagine-image/v2.0/edit",
 		endpoint: "xai/grok-imagine-image/v2.0/text-to-image",
 		falPricing: {
@@ -1557,35 +1695,25 @@ const MODELS = {
 	}
 };
 [
-	"flare",
 	"sunburst",
+	"flare",
 	"gpt2",
 	"gpt",
+	"banana21",
 	"banana2",
 	"banana",
-	"gemini",
-	"gemini3",
-	"seedream4",
-	"seedream45",
+	"mai-image-2.5",
+	"mai-image-2.5-pro",
 	"seedream5",
-	"seedream5-lite",
-	"flux2-max",
-	"flux2-pro",
+	"qwen3",
+	"banana2-lite",
+	"grok-image-2",
+	"grok-image",
 	"flux2-flex",
-	"flux2-dev",
+	"flux2-pro",
 	"flux2-turbo",
-	"flux",
-	"flux-fast",
-	"recraft",
-	"recraft4",
-	"ideogram",
+	"seedream5-lite",
 	"ideogram4",
-	"grok-image",
-	"grok-image-2",
-	"qwen",
-	"qwen3",
-	"mai-image-2.5-pro",
-	"banana2-lite",
 	"ideogram3-transparent",
 	"recraft41"
 ].filter((id) => MODELS[id]?.supportsEdit === true);