@howells/motif-sdk 5.2.0 → 5.4.0

package/README.md

@@ -34,17 +34,17 @@ Every Task function returns `Result<TaskOutput, MotifError>` from `neverthrow` a
 
 ## 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.
+The Task client curates 24 generation Models, with separate rankings for generation and editing. Both follow Arena, read 29 October 2026. `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   |
+| `balanced` (default) | Nano Banana 2.1    | Grok Image 2      |
 | `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.
+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 run GPT Image 2.6 on fal and default to `quality: "max"`; `params: { quality: "high" }` with an explicit `model` overrides it. Both also return an animated GIF (`outputFormat: "gif"`, with `params.frame_count` and `params.frame_duration_ms`) or, from text, an SVG (`outputFormat: "svg"`), and take `markup`: a transparent PNG of arrows, circles and notes the size of the image being edited, which guides a vary or an edit with References. Asking for a format or markup limits the choice to Models that support 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.
 
@@ -161,28 +161,28 @@ Four providers are implemented, each reading its own API key from the environmen
 | Provider | Env var | Notes |
 | --- | --- | --- |
 | `openrouter` | `OPENROUTER_API_KEY` | Default provider; Gemini gen + edit through OpenRouter (`google/*`), no masks |
-| `openai` | `OPENAI_API_KEY` | GPT Image 2.5 Flare and Sunburst |
+| `openai` | `OPENAI_API_KEY` | GPT Image 2.6 Flare and Sunburst |
 | `replicate` | `REPLICATE_API_TOKEN` | flux-1.1-pro-ultra |
 | `fal` | `FAL_KEY` | fal-hosted adapter |
 
 `generate()` and `edit()` take a provider model id; Task resolution chooses which model to pass, not the image layer. Every result carries a normalized per-call `cost: { usd, source }`.
 
-Both `gpt-image-2.5-flare` and `gpt-image-2.5-sunburst` support generation and multi-image editing:
+Both `gpt-image-2.6-flare` and `gpt-image-2.6-sunburst` support generation and multi-image editing:
 
 ```ts
 const image = createMotifImage({ defaultProvider: "openai" });
 const generated = await image.generate({
   prompt: "A ceramic vase in soft window light",
-  model: "gpt-image-2.5-flare",
+  model: "gpt-image-2.6-flare",
 });
 const refined = await image.edit({
   images: [referenceBytes],
   instruction: "Change only the vase glaze to deep green",
-  model: "gpt-image-2.5-sunburst",
+  model: "gpt-image-2.6-sunburst",
 });
 ```
 
-These models use token-based billing. Motif has no static per-image estimate for them, so `cost` is `{ usd: 0, source: "unknown" }` unless the provider supplies a cost; this does not mean generation is free. See the official [Flare](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare) and [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.5-sunburst) model pages. The installed OpenAI adapter accepts `low`, `medium`, `high`, and `auto` quality; the new `xhigh` and `max` settings require a future adapter update. The Task client and the CLI reach these models on fal as `flare` and `sunburst`. Fal supports `xhigh` and `max`, up to 16 edit references, masks and transparent backgrounds. Fal generation estimates are `null` (metered).
+These models use token-based billing. Motif has no static per-image estimate for them, so `cost` is `{ usd: 0, source: "unknown" }` unless the provider supplies a cost; this does not mean generation is free. See the official [Flare](https://developers.openai.com/api/docs/models/gpt-image-2.6-flare) and [Sunburst](https://developers.openai.com/api/docs/models/gpt-image-2.6-sunburst) model pages. Set quality (`auto`, `low`, `medium`, `high`, `xhigh` or `max`) and `background: "transparent"` through `providerOptions.openai`. The Task client and the CLI run the same models on fal as `flare` and `sunburst`, with up to 16 edit references, masks and transparent backgrounds. Fal generation estimates are `null` (metered).
 
 ### Best-of-N with an injectable judge
 
@@ -218,9 +218,3 @@ If some candidates fail, the judge sees only the survivors; if all `n` fail, `be
 pnpm --filter @howells/motif-sdk test
 pnpm --filter @howells/motif-sdk typecheck
 ```
-
-Live fal canaries are opt-in:
-
-```bash
-RUN_FAL_CANARY=1 pnpm --filter @howells/motif-sdk test -- tests/fal-canary.test.ts
-```

package/dist/image.js

@@ -57,6 +57,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: {
@@ -72,7 +73,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: {
@@ -82,11 +83,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,
@@ -94,8 +95,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",
@@ -124,7 +140,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: {
@@ -134,11 +150,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,
@@ -146,8 +162,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",
@@ -1413,6 +1444,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,
@@ -1423,12 +1455,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,
@@ -1631,6 +1664,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",
@@ -1708,7 +1855,10 @@ const MODELS = {
 	"qwen3",
 	"banana2-lite",
 	"grok-image-2",
+	"grok-image-quality",
 	"grok-image",
+	"muse-image",
+	"krea3",
 	"flux2-flex",
 	"flux2-pro",
 	"flux2-turbo",
@@ -1734,6 +1884,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,
@@ -3442,6 +3593,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,
@@ -3499,10 +3652,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 };
 /**