@howells/motif-sdk 5.3.0 → 6.0.0

package/README.md

@@ -44,7 +44,7 @@ The Task client curates 24 generation Models, with separate rankings for generat
 
 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.
 
@@ -73,14 +73,14 @@ if (plan.isOk()) {
 
 ## Stream a Task
 
-`stream(task, input, options?)` opens a direct inference stream on the resolved route. Streaming is explicitly supported for GPT Image 2, GPT Image 1.5 and FLUX.2 Dev, including their edit routes. Other routes return `STREAMING_UNSUPPORTED` before any provider request; Motif never substitutes another model or retries a stream.
+`stream(task, input, options?)` opens a direct inference stream on the resolved route. Streaming is explicitly supported for GPT Image 1.5 and FLUX.2 Dev, including their edit routes. Other routes return `STREAMING_UNSUPPORTED` before any provider request; Motif never substitutes another model or retries a stream.
 
 ```ts
 const controller = new AbortController();
 const opened = await motif.stream(
   "generate",
   {
-    model: "gpt2",
+    model: "gpt",
     prompt: "editorial product photo",
     references: ["https://example.com/reference.png"],
   },
@@ -110,7 +110,7 @@ For a local checkout, `node packages/motif-sdk/examples/stream.mjs --dry-run` pr
 - `ASPECT_RATIOS`, `RESOLUTIONS`, `FORMAT_PRESETS` - shared sizing metadata.
 - `LOOKS`, `CREATIVE_TAXONOMY`, `enrichPrompt`, `validateCreativeDirection` - house looks and moods.
 - `formatCost`, `sumCosts` - cost formatting and totals.
-- `getFalKeyFromEnv`, `getOpenAiKeyFromEnv` - `@howells/envy` backed key parsing.
+- `getFalKeyFromEnv` - `@howells/envy` backed key parsing.
 - Re-exported `neverthrow` helpers: `ok`, `err`, `Result`, `ResultAsync`.
 
 ## Common Types
@@ -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

@@ -73,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: {
@@ -83,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,
@@ -95,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",
@@ -125,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: {
@@ -135,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,
@@ -147,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",
@@ -163,77 +193,6 @@ const MODELS = {
 		type: "generation",
 		useQueue: true
 	},
-	gpt2: {
-		benchmark: {
-			artificialAnalysis: {
-				editing: {
-					elo: 1125,
-					rank: 5
-				},
-				snapshotDate: AA_IMAGE_LEADERBOARD_SNAPSHOT,
-				sourceUrls: AA_IMAGE_SOURCES,
-				textToImage: {
-					elo: 1172,
-					rank: 3
-				}
-			},
-			speed: {
-				medianSeconds: 200.7,
-				p95Seconds: 232.6,
-				source: "artificial-analysis-models"
-			},
-			tiers: {
-				price: "ultra",
-				quality: "frontier",
-				speed: "very_slow"
-			},
-			useCase: "Established frontier generation and transparent PNGs"
-		},
-		customImageSize: {
-			maxEdge: 3840,
-			maxPixels: 8294400,
-			maxRatio: 3,
-			minPixels: 655360,
-			multipleOf: 16
-		},
-		editEndpoint: "openai/gpt-image-2/edit",
-		endpoint: "openai/gpt-image-2",
-		falPricing: {
-			checkedAt: FAL_PRICING_CHECKED_AT,
-			currency: "USD",
-			endpointId: "openai/gpt-image-2",
-			estimatedCostPerImageUsd: .211,
-			source: "fal-pricing-api",
-			unit: "units",
-			unitPrice: 1
-		},
-		maxReferenceImages: 16,
-		name: "GPT Image 2",
-		pricePerImageUsd: .211,
-		pricing: "$0.211",
-		sizeMode: "image_size_enum",
-		supportsAspect: true,
-		streaming: {
-			generation: true,
-			edit: true
-		},
-		supportsEdit: true,
-		supportsMaskImage: true,
-		maskImageField: "mask_url",
-		supportsNumImages: true,
-		supportsOutputFormat: true,
-		supportsQuality: true,
-		supportsResolution: false,
-		supportsSyncMode: true,
-		transparencyRoute: {
-			apiKeyEnv: "OPENAI_API_KEY",
-			model: "gpt-image-2",
-			provider: "openai",
-			supportsEdit: true
-		},
-		type: "generation",
-		useQueue: true
-	},
 	gpt: {
 		benchmark: {
 			artificialAnalysis: {
@@ -1814,7 +1773,6 @@ const MODELS = {
 [
 	"sunburst",
 	"flare",
-	"gpt2",
 	"gpt",
 	"banana21",
 	"banana2",
@@ -1854,6 +1812,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,
@@ -1956,7 +1915,7 @@ Object.keys(OPTION_CAPABILITIES).filter(isModelOption);
 			experimental: true,
 			id: "illustration",
 			label: "Editorial illustration",
-			model: "gpt2"
+			model: "flare"
 		}
 	],
 	mood: [
@@ -3546,7 +3505,6 @@ const FAL_IMAGE_PRICE_USD = {
 	"fal-ai/flux-2": MODELS["flux2-dev"]?.pricePerImageUsd ?? .012,
 	"fal-ai/flux-2/turbo": MODELS["flux2-turbo"]?.pricePerImageUsd ?? .008,
 	[FAL_GPT_IMAGE_MODEL]: MODELS.gpt?.pricePerImageUsd ?? .133,
-	"openai/gpt-image-2": MODELS.gpt2?.pricePerImageUsd ?? .211,
 	"fal-ai/nano-banana-2": MODELS.banana2?.pricePerImageUsd ?? .08,
 	"fal-ai/nano-banana-pro": MODELS.banana?.pricePerImageUsd ?? .15,
 	"fal-ai/gemini-25-flash-image": MODELS.gemini?.pricePerImageUsd ?? .0398,
@@ -3621,10 +3579,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 };
 /**