@howells/motif-sdk 1.3.1 → 2.0.0

package/README.md

@@ -171,12 +171,29 @@ Four providers are implemented, each reading its own API key from the environmen
 | Provider | Env var | Notes |
 | --- | --- | --- |
 | `google` | `GOOGLE_GENERATIVE_AI_API_KEY` | Default provider; Gemini gen + edit |
-| `openai` | `OPENAI_API_KEY` | gpt-image-1 |
+| `openai` | `OPENAI_API_KEY` | GPT Image 2.5 Flare (fast/balanced), Sunburst (quality/hero) |
 | `replicate` | `REPLICATE_API_TOKEN` | flux-1.1-pro-ultra |
 | `fal` | `FAL_KEY` | fal-hosted adapter |
 
 `generate()` and `edit()` accept `tier` (`"fast" | "balanced" | "quality" | "hero"`) to resolve a model per provider, or an explicit `model` id. Every result carries a normalized per-call `cost: { usd, source }`.
 
+For OpenAI, `fast` and `balanced` (the default tier) select `gpt-image-2.5-flare`; `quality` and `hero` select `gpt-image-2.5-sunburst`. This updates the previous OpenAI tier default of `gpt-image-1`; pass that explicit model to retain it. Both new models 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",
+});
+const refined = await image.edit({
+  images: [referenceBytes],
+  instruction: "Change only the vase glaze to deep green",
+  model: "gpt-image-2.5-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 fal-backed CLI and `FalClient` expose these models as `flare` and `sunburst`. Fal supports `xhigh` and `max`, up to 16 edit references, masks and transparent backgrounds. Fal generation estimates are `null` (metered), including `estimateCost()` and queued jobs.
+
 ### Best-of-N with an injectable judge
 
 `bestOfN()` generates `n` candidates in parallel and picks a winner. It reuses the same options as `generate()` (text→image) or `edit()` (pass `images` for the edit path), plus `n` and an optional `judge`. When a `seed` is given each candidate uses `seed + index`, so the N vary. The judge is a caller-provided function — the layer takes no text-client dependency, so it pairs well with `@howells/ai`'s vision client but does not require it. Omit the judge and candidate 0 wins.

package/dist/image.d.ts

@@ -304,7 +304,10 @@ export declare const GOOGLE_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 export declare const GOOGLE_API_KEY_ENV = "GOOGLE_GENERATIVE_AI_API_KEY";
 //#endregion
 //#region src/image/openai.d.ts
-/** Tier → OpenAI image model id (all tiers → the single gpt-image model). */
+/**
+ * Flare favors speed for everyday generation; Sunburst favors editing precision.
+ * Explicit model ids still override tiers, including older GPT Image models.
+ */
 export declare const OPENAI_TIER_MODELS: Readonly<Record<ImageTier, string>>;
 /** Env var read for the OpenAI API key when `apiKey` is not supplied in config. */
 export declare const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";

package/dist/image.js

@@ -10,6 +10,64 @@ const AA_IMAGE_SOURCES = ["https://artificialanalysis.ai/image/leaderboard/text-
 const FAL_PRICING_CHECKED_AT = "2026-05-12";
 const FAL_PRICING_CHECKED_JUL_2026 = "2026-07-11";
 const MODELS = {
+	flare: {
+		editEndpoint: "openai/gpt-image-2.5/flare/edit",
+		endpoint: "openai/gpt-image-2.5/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",
+		pricePerImageUsd: null,
+		sizeMode: "image_size_enum",
+		supportsAspect: true,
+		supportsBackground: true,
+		supportsEdit: true,
+		supportsMaskImage: true,
+		maskImageField: "mask_url",
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsQuality: true,
+		supportedQualities: [
+			"auto",
+			"low",
+			"medium",
+			"high",
+			"xhigh",
+			"max"
+		],
+		supportsResolution: false,
+		supportsSyncMode: true,
+		type: "generation",
+		useQueue: true
+	},
+	sunburst: {
+		editEndpoint: "openai/gpt-image-2.5/sunburst/edit",
+		endpoint: "openai/gpt-image-2.5/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",
+		pricePerImageUsd: null,
+		sizeMode: "image_size_enum",
+		supportsAspect: true,
+		supportsBackground: true,
+		supportsEdit: true,
+		supportsMaskImage: true,
+		maskImageField: "mask_url",
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsQuality: true,
+		supportedQualities: [
+			"auto",
+			"low",
+			"medium",
+			"high",
+			"xhigh",
+			"max"
+		],
+		supportsResolution: false,
+		supportsSyncMode: true,
+		type: "generation",
+		useQueue: true
+	},
 	gpt2: {
 		benchmark: {
 			artificialAnalysis: {
@@ -1104,6 +1162,8 @@ const MODELS = {
 	}
 };
 [
+	"flare",
+	"sunburst",
 	"gpt2",
 	"gpt",
 	"banana2",
@@ -2573,18 +2633,14 @@ const googleAdapter = {
 * invokes `model.doGenerate`.
 */
 /**
-* OpenAI's image API currently exposes a single gpt-image model, so every tier
-* maps to `gpt-image-1`. Tiers will later differ by `quality`
-* (low/medium/high/auto) passed via `providerOptions.openai` (Phase 1c); until
-* then the tier only selects this one model.
+* Flare favors speed for everyday generation; Sunburst favors editing precision.
+* Explicit model ids still override tiers, including older GPT Image models.
 */
-const OPENAI_MODEL = "gpt-image-1";
-/** Tier → OpenAI image model id (all tiers → the single gpt-image model). */
 const OPENAI_TIER_MODELS = {
-	fast: OPENAI_MODEL,
-	balanced: OPENAI_MODEL,
-	quality: OPENAI_MODEL,
-	hero: OPENAI_MODEL
+	fast: "gpt-image-2.5-flare",
+	balanced: "gpt-image-2.5-flare",
+	quality: "gpt-image-2.5-sunburst",
+	hero: "gpt-image-2.5-sunburst"
 };
 /** Env var read for the OpenAI API key when `apiKey` is not supplied in config. */
 const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
@@ -2597,6 +2653,11 @@ const OPENAI_API_KEY_ENV = "OPENAI_API_KEY";
 * Source: https://platform.openai.com/docs/pricing (image generation)
 * Sanity anchor: the Phase 0 benchmark measured gpt-image direct at $0.042
 * (vs $0.133 via fal — see docs/design/provider-agnostic-image-layer.md §10).
+*
+* GPT Image 2.5 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
 */
 const OPENAI_IMAGE_PRICE_USD = { "gpt-image-1": .042 };
 /**

package/dist/index.cjs

@@ -112,6 +112,64 @@ const AA_IMAGE_SOURCES = ["https://artificialanalysis.ai/image/leaderboard/text-
 const FAL_PRICING_CHECKED_AT = "2026-05-12";
 const FAL_PRICING_CHECKED_JUL_2026 = "2026-07-11";
 const MODELS = {
+	flare: {
+		editEndpoint: "openai/gpt-image-2.5/flare/edit",
+		endpoint: "openai/gpt-image-2.5/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",
+		pricePerImageUsd: null,
+		sizeMode: "image_size_enum",
+		supportsAspect: true,
+		supportsBackground: true,
+		supportsEdit: true,
+		supportsMaskImage: true,
+		maskImageField: "mask_url",
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsQuality: true,
+		supportedQualities: [
+			"auto",
+			"low",
+			"medium",
+			"high",
+			"xhigh",
+			"max"
+		],
+		supportsResolution: false,
+		supportsSyncMode: true,
+		type: "generation",
+		useQueue: true
+	},
+	sunburst: {
+		editEndpoint: "openai/gpt-image-2.5/sunburst/edit",
+		endpoint: "openai/gpt-image-2.5/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",
+		pricePerImageUsd: null,
+		sizeMode: "image_size_enum",
+		supportsAspect: true,
+		supportsBackground: true,
+		supportsEdit: true,
+		supportsMaskImage: true,
+		maskImageField: "mask_url",
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsQuality: true,
+		supportedQualities: [
+			"auto",
+			"low",
+			"medium",
+			"high",
+			"xhigh",
+			"max"
+		],
+		supportsResolution: false,
+		supportsSyncMode: true,
+		type: "generation",
+		useQueue: true
+	},
 	gpt2: {
 		benchmark: {
 			artificialAnalysis: {
@@ -1206,6 +1264,8 @@ const MODELS = {
 	}
 };
 const GENERATION_MODELS = [
+	"flare",
+	"sunburst",
 	"gpt2",
 	"gpt",
 	"banana2",
@@ -1288,6 +1348,7 @@ const IDEOGRAM_STYLES = [
 /** Estimate cost based on model and settings */
 function estimateCost(model, resolution, numImages = 1) {
 	const configuredPrice = MODELS[model]?.pricePerImageUsd;
+	if (configuredPrice === null) return null;
 	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;
@@ -1513,6 +1574,15 @@ function validateGenerateOptions(options, config, sizeMode, hasEditImages) {
 	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");
+	if (options.quality !== void 0) {
+		const qualities = config.supportedQualities ?? [
+			"auto",
+			"low",
+			"medium",
+			"high"
+		];
+		if (!qualities.includes(options.quality)) throw new Error(`${config.name} quality must be one of ${qualities.join(", ")}`);
+	}
 	if (options.negativePrompt !== void 0 && config.supportsNegativePrompt !== true) unsupported(config, "negativePrompt");
 	if (options.style !== void 0 && config.supportsStyle !== true) unsupported(config, "style");
 	if (options.syncMode !== void 0 && config.supportsSyncMode !== true) unsupported(config, "syncMode");
@@ -1631,7 +1701,7 @@ function buildGenerateBody(options) {
 		body.image_urls = editImages;
 		if (inputFidelity) body.input_fidelity = inputFidelity;
 	}
-	if (maskImageUrl !== void 0 && maskImageUrl !== "" && config.supportsMaskImage === true) body.mask_image_url = maskImageUrl;
+	if (maskImageUrl !== void 0 && maskImageUrl !== "" && config.supportsMaskImage === true) body[config.maskImageField ?? "mask_image_url"] = maskImageUrl;
 	return {
 		body,
 		endpoint

package/dist/index.d.cts

@@ -145,7 +145,7 @@ type Resolution = "0.5K" | "1K" | "2K" | "4K";
 type ModelType = "generation" | "utility" | "video";
 type ImageOutputFormat = "jpeg" | "png" | "webp";
 type BackgroundMode = "auto" | "transparent" | "opaque";
-type ImageQuality = "auto" | "low" | "medium" | "high";
+type ImageQuality = "auto" | "low" | "medium" | "high" | "xhigh" | "max";
 type ThinkingLevel = "minimal" | "high";
 type GptImageSize = "auto" | "1024x1024" | "1536x1024" | "1024x1536";
 type FalImageSizePreset = "auto" | "square_hd" | "square" | "portrait_4_3" | "portrait_16_9" | "landscape_4_3" | "landscape_16_9";
@@ -201,7 +201,8 @@ interface ModelConfig {
   maxReferenceImages?: number;
   name: string;
   pricing: string;
-  pricePerImageUsd?: number;
+  /** Null means token-metered with no per-image estimate. */
+  pricePerImageUsd?: number | null;
   /** How this model accepts dimensions (default: "aspect_ratio") */
   sizeMode?: SizeMode;
   supportsAspect: boolean;
@@ -215,11 +216,13 @@ interface ModelConfig {
   supportsInferenceSteps?: boolean;
   supportsLimitGenerations?: boolean;
   supportsMaskImage?: boolean;
+  maskImageField?: "mask_image_url" | "mask_url";
   supportsNegativePrompt?: boolean;
   supportsNumImages: boolean;
   supportsOutputFormat?: boolean;
   supportedOutputFormats?: readonly ImageOutputFormat[];
   supportsQuality?: boolean;
+  supportedQualities?: readonly ImageQuality[];
   supportsRaw?: boolean;
   supportsRenderingSpeed?: boolean;
   supportsResolution: boolean;
@@ -373,7 +376,7 @@ interface MotifResponse {
 /** ─── Queue Types ────────────────────────────────────────────── */
 interface QueuedJob {
   endpoint: string;
-  estimatedCost: number;
+  estimatedCost: number | null;
   requestId: string;
 }
 interface JobStatus {
@@ -428,7 +431,7 @@ export declare const FORMAT_PRESETS: Record<string, {
 //#endregion
 //#region src/cost.d.ts
 /** Estimate cost based on model and settings */
-export declare function estimateCost(model: string, resolution?: Resolution, numImages?: number): number;
+export declare function estimateCost(model: string, resolution?: Resolution, numImages?: number): number | null;
 /** Estimate cost for video generation */
 export declare function estimateVideoCost(durationSeconds?: number, generateAudio?: boolean): number;
 //#endregion
@@ -485,9 +488,9 @@ export declare const VIDEO_IMAGE_TO_VIDEO_TOP_15: LeaderboardSnapshot;
 //#endregion
 //#region src/models.d.ts
 export declare const MODELS: Record<string, ModelConfig>;
-export declare const GENERATION_MODELS: readonly ["gpt2", "gpt", "banana2", "banana", "gemini", "gemini3", "seedream4", "seedream45", "seedream5", "seedream5-lite", "flux2-max", "flux2-pro", "flux2-flex", "flux2-dev", "flux2-turbo", "flux", "flux-fast", "recraft", "recraft4", "ideogram", "ideogram4", "grok-image", "qwen", "qwen3"];
+export declare const GENERATION_MODELS: readonly ["flare", "sunburst", "gpt2", "gpt", "banana2", "banana", "gemini", "gemini3", "seedream4", "seedream45", "seedream5", "seedream5-lite", "flux2-max", "flux2-pro", "flux2-flex", "flux2-dev", "flux2-turbo", "flux", "flux-fast", "recraft", "recraft4", "ideogram", "ideogram4", "grok-image", "qwen", "qwen3"];
 /** Models whose fal endpoints support image editing (vary/edit flows). */
-export declare const EDIT_CAPABLE_MODELS: ("banana" | "banana2" | "flux" | "flux-fast" | "flux2-dev" | "flux2-flex" | "flux2-max" | "flux2-pro" | "flux2-turbo" | "gemini" | "gemini3" | "gpt" | "gpt2" | "grok-image" | "ideogram" | "ideogram4" | "qwen" | "qwen3" | "recraft" | "recraft4" | "seedream4" | "seedream45" | "seedream5" | "seedream5-lite")[];
+export declare const EDIT_CAPABLE_MODELS: ("banana" | "banana2" | "flare" | "flux" | "flux-fast" | "flux2-dev" | "flux2-flex" | "flux2-max" | "flux2-pro" | "flux2-turbo" | "gemini" | "gemini3" | "gpt" | "gpt2" | "grok-image" | "ideogram" | "ideogram4" | "qwen" | "qwen3" | "recraft" | "recraft4" | "seedream4" | "seedream45" | "seedream5" | "seedream5-lite" | "sunburst")[];
 export declare const UTILITY_MODELS: readonly ["clarity", "crystal", "rmbg", "bria"];
 export declare const VIDEO_MODELS: readonly ["kling"];
 type GenerationModelName = (typeof GENERATION_MODELS)[number];
@@ -608,7 +611,7 @@ export declare class FalClient {
    */
   deletePayloads(requestId: string): Promise<Result$1<void, MotifError>>;
   /** Estimate cost for a generation (no API call). */
-  estimateCost(model: string, resolution?: Resolution, numImages?: number): number;
+  estimateCost(model: string, resolution?: Resolution, numImages?: number): number | null;
   /** Build the fal.ai request body without sending it. */
   buildRequestBody(options: GenerateOptions): {
     endpoint: string;
@@ -617,7 +620,7 @@ export declare class FalClient {
   /** Model registry. */
   get models(): Record<string, ModelConfig>;
   /** Generation model keys. */
-  get generationModels(): readonly ["gpt2", "gpt", "banana2", "banana", "gemini", "gemini3", "seedream4", "seedream45", "seedream5", "seedream5-lite", "flux2-max", "flux2-pro", "flux2-flex", "flux2-dev", "flux2-turbo", "flux", "flux-fast", "recraft", "recraft4", "ideogram", "ideogram4", "grok-image", "qwen", "qwen3"];
+  get generationModels(): readonly ["flare", "sunburst", "gpt2", "gpt", "banana2", "banana", "gemini", "gemini3", "seedream4", "seedream45", "seedream5", "seedream5-lite", "flux2-max", "flux2-pro", "flux2-flex", "flux2-dev", "flux2-turbo", "flux", "flux-fast", "recraft", "recraft4", "ideogram", "ideogram4", "grok-image", "qwen", "qwen3"];
   /** Utility model keys. */
   get utilityModels(): readonly ["clarity", "crystal", "rmbg", "bria"];
   /** Registered fal utility/tool endpoints. */

package/dist/index.d.ts

@@ -145,7 +145,7 @@ type Resolution = "0.5K" | "1K" | "2K" | "4K";
 type ModelType = "generation" | "utility" | "video";
 type ImageOutputFormat = "jpeg" | "png" | "webp";
 type BackgroundMode = "auto" | "transparent" | "opaque";
-type ImageQuality = "auto" | "low" | "medium" | "high";
+type ImageQuality = "auto" | "low" | "medium" | "high" | "xhigh" | "max";
 type ThinkingLevel = "minimal" | "high";
 type GptImageSize = "auto" | "1024x1024" | "1536x1024" | "1024x1536";
 type FalImageSizePreset = "auto" | "square_hd" | "square" | "portrait_4_3" | "portrait_16_9" | "landscape_4_3" | "landscape_16_9";
@@ -201,7 +201,8 @@ interface ModelConfig {
   maxReferenceImages?: number;
   name: string;
   pricing: string;
-  pricePerImageUsd?: number;
+  /** Null means token-metered with no per-image estimate. */
+  pricePerImageUsd?: number | null;
   /** How this model accepts dimensions (default: "aspect_ratio") */
   sizeMode?: SizeMode;
   supportsAspect: boolean;
@@ -215,11 +216,13 @@ interface ModelConfig {
   supportsInferenceSteps?: boolean;
   supportsLimitGenerations?: boolean;
   supportsMaskImage?: boolean;
+  maskImageField?: "mask_image_url" | "mask_url";
   supportsNegativePrompt?: boolean;
   supportsNumImages: boolean;
   supportsOutputFormat?: boolean;
   supportedOutputFormats?: readonly ImageOutputFormat[];
   supportsQuality?: boolean;
+  supportedQualities?: readonly ImageQuality[];
   supportsRaw?: boolean;
   supportsRenderingSpeed?: boolean;
   supportsResolution: boolean;
@@ -373,7 +376,7 @@ interface MotifResponse {
 /** ─── Queue Types ────────────────────────────────────────────── */
 interface QueuedJob {
   endpoint: string;
-  estimatedCost: number;
+  estimatedCost: number | null;
   requestId: string;
 }
 interface JobStatus {
@@ -428,7 +431,7 @@ export declare const FORMAT_PRESETS: Record<string, {
 //#endregion
 //#region src/cost.d.ts
 /** Estimate cost based on model and settings */
-export declare function estimateCost(model: string, resolution?: Resolution, numImages?: number): number;
+export declare function estimateCost(model: string, resolution?: Resolution, numImages?: number): number | null;
 /** Estimate cost for video generation */
 export declare function estimateVideoCost(durationSeconds?: number, generateAudio?: boolean): number;
 //#endregion
@@ -485,9 +488,9 @@ export declare const VIDEO_IMAGE_TO_VIDEO_TOP_15: LeaderboardSnapshot;
 //#endregion
 //#region src/models.d.ts
 export declare const MODELS: Record<string, ModelConfig>;
-export declare const GENERATION_MODELS: readonly ["gpt2", "gpt", "banana2", "banana", "gemini", "gemini3", "seedream4", "seedream45", "seedream5", "seedream5-lite", "flux2-max", "flux2-pro", "flux2-flex", "flux2-dev", "flux2-turbo", "flux", "flux-fast", "recraft", "recraft4", "ideogram", "ideogram4", "grok-image", "qwen", "qwen3"];
+export declare const GENERATION_MODELS: readonly ["flare", "sunburst", "gpt2", "gpt", "banana2", "banana", "gemini", "gemini3", "seedream4", "seedream45", "seedream5", "seedream5-lite", "flux2-max", "flux2-pro", "flux2-flex", "flux2-dev", "flux2-turbo", "flux", "flux-fast", "recraft", "recraft4", "ideogram", "ideogram4", "grok-image", "qwen", "qwen3"];
 /** Models whose fal endpoints support image editing (vary/edit flows). */
-export declare const EDIT_CAPABLE_MODELS: ("banana" | "banana2" | "flux" | "flux-fast" | "flux2-dev" | "flux2-flex" | "flux2-max" | "flux2-pro" | "flux2-turbo" | "gemini" | "gemini3" | "gpt" | "gpt2" | "grok-image" | "ideogram" | "ideogram4" | "qwen" | "qwen3" | "recraft" | "recraft4" | "seedream4" | "seedream45" | "seedream5" | "seedream5-lite")[];
+export declare const EDIT_CAPABLE_MODELS: ("banana" | "banana2" | "flare" | "flux" | "flux-fast" | "flux2-dev" | "flux2-flex" | "flux2-max" | "flux2-pro" | "flux2-turbo" | "gemini" | "gemini3" | "gpt" | "gpt2" | "grok-image" | "ideogram" | "ideogram4" | "qwen" | "qwen3" | "recraft" | "recraft4" | "seedream4" | "seedream45" | "seedream5" | "seedream5-lite" | "sunburst")[];
 export declare const UTILITY_MODELS: readonly ["clarity", "crystal", "rmbg", "bria"];
 export declare const VIDEO_MODELS: readonly ["kling"];
 type GenerationModelName = (typeof GENERATION_MODELS)[number];
@@ -608,7 +611,7 @@ export declare class FalClient {
    */
   deletePayloads(requestId: string): Promise<Result$1<void, MotifError>>;
   /** Estimate cost for a generation (no API call). */
-  estimateCost(model: string, resolution?: Resolution, numImages?: number): number;
+  estimateCost(model: string, resolution?: Resolution, numImages?: number): number | null;
   /** Build the fal.ai request body without sending it. */
   buildRequestBody(options: GenerateOptions): {
     endpoint: string;
@@ -617,7 +620,7 @@ export declare class FalClient {
   /** Model registry. */
   get models(): Record<string, ModelConfig>;
   /** Generation model keys. */
-  get generationModels(): readonly ["gpt2", "gpt", "banana2", "banana", "gemini", "gemini3", "seedream4", "seedream45", "seedream5", "seedream5-lite", "flux2-max", "flux2-pro", "flux2-flex", "flux2-dev", "flux2-turbo", "flux", "flux-fast", "recraft", "recraft4", "ideogram", "ideogram4", "grok-image", "qwen", "qwen3"];
+  get generationModels(): readonly ["flare", "sunburst", "gpt2", "gpt", "banana2", "banana", "gemini", "gemini3", "seedream4", "seedream45", "seedream5", "seedream5-lite", "flux2-max", "flux2-pro", "flux2-flex", "flux2-dev", "flux2-turbo", "flux", "flux-fast", "recraft", "recraft4", "ideogram", "ideogram4", "grok-image", "qwen", "qwen3"];
   /** Utility model keys. */
   get utilityModels(): readonly ["clarity", "crystal", "rmbg", "bria"];
   /** Registered fal utility/tool endpoints. */

package/dist/index.js

@@ -111,6 +111,64 @@ const AA_IMAGE_SOURCES = ["https://artificialanalysis.ai/image/leaderboard/text-
 const FAL_PRICING_CHECKED_AT = "2026-05-12";
 const FAL_PRICING_CHECKED_JUL_2026 = "2026-07-11";
 const MODELS = {
+	flare: {
+		editEndpoint: "openai/gpt-image-2.5/flare/edit",
+		endpoint: "openai/gpt-image-2.5/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",
+		pricePerImageUsd: null,
+		sizeMode: "image_size_enum",
+		supportsAspect: true,
+		supportsBackground: true,
+		supportsEdit: true,
+		supportsMaskImage: true,
+		maskImageField: "mask_url",
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsQuality: true,
+		supportedQualities: [
+			"auto",
+			"low",
+			"medium",
+			"high",
+			"xhigh",
+			"max"
+		],
+		supportsResolution: false,
+		supportsSyncMode: true,
+		type: "generation",
+		useQueue: true
+	},
+	sunburst: {
+		editEndpoint: "openai/gpt-image-2.5/sunburst/edit",
+		endpoint: "openai/gpt-image-2.5/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",
+		pricePerImageUsd: null,
+		sizeMode: "image_size_enum",
+		supportsAspect: true,
+		supportsBackground: true,
+		supportsEdit: true,
+		supportsMaskImage: true,
+		maskImageField: "mask_url",
+		supportsNumImages: true,
+		supportsOutputFormat: true,
+		supportsQuality: true,
+		supportedQualities: [
+			"auto",
+			"low",
+			"medium",
+			"high",
+			"xhigh",
+			"max"
+		],
+		supportsResolution: false,
+		supportsSyncMode: true,
+		type: "generation",
+		useQueue: true
+	},
 	gpt2: {
 		benchmark: {
 			artificialAnalysis: {
@@ -1205,6 +1263,8 @@ const MODELS = {
 	}
 };
 const GENERATION_MODELS = [
+	"flare",
+	"sunburst",
 	"gpt2",
 	"gpt",
 	"banana2",
@@ -1287,6 +1347,7 @@ const IDEOGRAM_STYLES = [
 /** Estimate cost based on model and settings */
 function estimateCost(model, resolution, numImages = 1) {
 	const configuredPrice = MODELS[model]?.pricePerImageUsd;
+	if (configuredPrice === null) return null;
 	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;
@@ -1512,6 +1573,15 @@ function validateGenerateOptions(options, config, sizeMode, hasEditImages) {
 	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");
+	if (options.quality !== void 0) {
+		const qualities = config.supportedQualities ?? [
+			"auto",
+			"low",
+			"medium",
+			"high"
+		];
+		if (!qualities.includes(options.quality)) throw new Error(`${config.name} quality must be one of ${qualities.join(", ")}`);
+	}
 	if (options.negativePrompt !== void 0 && config.supportsNegativePrompt !== true) unsupported(config, "negativePrompt");
 	if (options.style !== void 0 && config.supportsStyle !== true) unsupported(config, "style");
 	if (options.syncMode !== void 0 && config.supportsSyncMode !== true) unsupported(config, "syncMode");
@@ -1630,7 +1700,7 @@ function buildGenerateBody(options) {
 		body.image_urls = editImages;
 		if (inputFidelity) body.input_fidelity = inputFidelity;
 	}
-	if (maskImageUrl !== void 0 && maskImageUrl !== "" && config.supportsMaskImage === true) body.mask_image_url = maskImageUrl;
+	if (maskImageUrl !== void 0 && maskImageUrl !== "" && config.supportsMaskImage === true) body[config.maskImageField ?? "mask_image_url"] = maskImageUrl;
 	return {
 		body,
 		endpoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@howells/motif-sdk",
-  "version": "1.3.1",
+  "version": "2.0.0",
   "description": "Public Node SDK for Motif fal.ai generation, editing, utility tools, and model metadata.",
   "keywords": [
     "fal",