@howells/motif-sdk 0.12.0 → 1.0.0

package/README.md

@@ -10,10 +10,14 @@ npm install @howells/motif-sdk
 
 ## Generate Images
 
+The primary image API is `createMotifImage` (`@howells/motif-sdk/image`) — provider-agnostic generate/edit across google, openai, replicate, and fal. See [Image Layer](#image-layer-howellsmotif-sdkimage) below.
+
+The examples in this section use the low-level `FalClient`, the fal-native client for fal-specific capabilities (queue, upload, upscale, background removal, video, and utility tools).
+
 ```ts
-import { MotifServer } from "@howells/motif-sdk";
+import { FalClient } from "@howells/motif-sdk";
 
-const motif = new MotifServer({
+const motif = new FalClient({
   apiKey: process.env.FAL_KEY!,
   retries: 3,
   timeout: 120_000,
@@ -103,7 +107,8 @@ const videoJob = await motif.submitVideo({
 
 ## Main Exports
 
-- `MotifServer` - Result-returning fal client for generation, queue jobs, upload, utility tools, and payload deletion.
+- `createMotifImage` (`@howells/motif-sdk/image`) - the primary image API: provider-agnostic generate/edit/best-of-N across google, openai, replicate, and fal.
+- `FalClient` - low-level fal-native client for generation, queue jobs, upload, utility tools, and payload deletion.
 - `buildGenerateBody` - Pure fal request normalization for dry runs and tests.
 - `MODELS`, `GENERATION_MODELS`, `UTILITY_MODELS`, `VIDEO_MODELS` - Motif model aliases, fal endpoints, capabilities, pricing, and benchmarks.
 - `FAL_TOOLS`, `FAL_TOOL_IDS`, `buildFalToolRequest`, `isFalToolId` - Normalized fal utility endpoints such as SAM, depth, upscaling, moderation, and background removal.
@@ -119,13 +124,13 @@ The package exports public types for generation, processing, queue, metadata, an
 
 - `GenerateOptions`, `MotifResponse`, `MotifImage`
 - `UpscaleOptions`, `RemoveBackgroundOptions`, `VideoOptions`, `VideoResponse`
-- `QueuedJob`, `JobStatus`, `MotifServerConfig`
+- `QueuedJob`, `JobStatus`, `FalClientConfig`
 - `ModelConfig`, `AspectRatio`, `Resolution`, `ImageSize`, `ImageQuality`, `BackgroundMode`, `ThinkingLevel`
 - `FalToolConfig`, `FalToolId`, `FalToolRequest`, `FalToolRunOptions`
 
 ## Image Layer (`@howells/motif-sdk/image`)
 
-A provider-agnostic image generation + editing layer, additive to the fal-specific `MotifServer` surface above. It is an ESM-only subpath export, built on the Vercel AI SDK image interface (`ai`'s `generateImage`).
+The primary, provider-agnostic image generation + editing layer — the recommended way to generate and edit images. The fal-specific `FalClient` surface above stays for fal-native extras. It is an ESM-only subpath export, built on the Vercel AI SDK image interface (`ai`'s `generateImage`).
 
 ```bash
 npm install @howells/motif-sdk

package/dist/index.cjs

@@ -36,7 +36,6 @@ __export(src_exports, {
   IMAGE_TEXT_TO_IMAGE_TOP_20: () => IMAGE_TEXT_TO_IMAGE_TOP_20,
   MODELS: () => MODELS,
   MotifError: () => MotifError,
-  MotifServer: () => MotifServer,
   RECRAFT_STYLES: () => RECRAFT_STYLES,
   RESOLUTIONS: () => RESOLUTIONS,
   UTILITY_MODELS: () => UTILITY_MODELS,
@@ -3237,7 +3236,6 @@ var FalClient = class {
     });
   }
 };
-var MotifServer = FalClient;
 var MotifError = class extends Error {
   status;
   code;
@@ -3278,7 +3276,6 @@ function toMotifError(error) {
   IMAGE_TEXT_TO_IMAGE_TOP_20,
   MODELS,
   MotifError,
-  MotifServer,
   RECRAFT_STYLES,
   RESOLUTIONS,
   UTILITY_MODELS,

package/dist/index.d.cts

@@ -395,8 +395,6 @@ interface FalClientConfig {
     /** Request timeout in ms (default 120_000) */
     timeout?: number;
 }
-/** @deprecated Renamed to {@link FalClientConfig}. */
-type MotifServerConfig = FalClientConfig;
 
 /** Ordered by popularity: square first, then common ratios */
 declare const ASPECT_RATIOS: AspectRatio[];
@@ -930,8 +928,6 @@ declare class FalClient {
      */
     private normalizeResponse;
 }
-/** @deprecated Renamed to {@link FalClient}. `MotifServer` is kept as an alias for backwards compatibility and will be removed in 1.0. */
-declare const MotifServer: typeof FalClient;
 declare class MotifError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -1328,4 +1324,4 @@ type FalToolId = (typeof FAL_TOOL_IDS)[number];
 declare function isFalToolId(tool: string): tool is FalToolId;
 declare function buildFalToolRequest(options: FalToolRunOptions): FalToolRequest;
 
-export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, FalClient, type FalClientConfig, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };
+export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, FalClient, type FalClientConfig, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };

package/dist/index.d.ts

@@ -395,8 +395,6 @@ interface FalClientConfig {
     /** Request timeout in ms (default 120_000) */
     timeout?: number;
 }
-/** @deprecated Renamed to {@link FalClientConfig}. */
-type MotifServerConfig = FalClientConfig;
 
 /** Ordered by popularity: square first, then common ratios */
 declare const ASPECT_RATIOS: AspectRatio[];
@@ -930,8 +928,6 @@ declare class FalClient {
      */
     private normalizeResponse;
 }
-/** @deprecated Renamed to {@link FalClient}. `MotifServer` is kept as an alias for backwards compatibility and will be removed in 1.0. */
-declare const MotifServer: typeof FalClient;
 declare class MotifError extends Error {
     readonly status: number;
     readonly code?: string;
@@ -1328,4 +1324,4 @@ type FalToolId = (typeof FAL_TOOL_IDS)[number];
 declare function isFalToolId(tool: string): tool is FalToolId;
 declare function buildFalToolRequest(options: FalToolRunOptions): FalToolRequest;
 
-export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, FalClient, type FalClientConfig, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, MotifServer, type MotifServerConfig, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };
+export { ASPECT_RATIOS, type AspectRatio, type BackgroundMode, CREATIVE_FIELDS, CREATIVE_TAXONOMY, type CreativeDirection, type CreativeField, type CreativeOption, CreativeOptionError, type CreativeOptionErrorDetails, type CreativePromptResult, type CustomImageSize, EDIT_CAPABLE_MODELS, type EnrichPromptOptions, FAL_TOOLS, FAL_TOOLS_CHECKED_AT, FAL_TOOL_IDS, FORMAT_PRESETS, FalClient, type FalClientConfig, type FalImageSizePreset, type FalToolConfig, type FalToolId, type FalToolInputKind, type FalToolRequest, type FalToolRunOptions, GENERATION_MODELS, type GenerateOptions, type GenerationModelName, type GptImageSize, IDEOGRAM_STYLES, IMAGE_EDITING_TOP_20, IMAGE_TEXT_TO_IMAGE_TOP_20, type ImageOutputFormat, type ImageQuality, type ImageSize, type JobStatus, type LeaderboardEntry, type LeaderboardSnapshot, MODELS, type ModelConfig, type ModelType, type MotifEnv, MotifError, type MotifImage, type MotifResponse, type QueuedJob, RECRAFT_STYLES, RESOLUTIONS, type RemoveBackgroundOptions, type Resolution, type SizeMode, type ThinkingLevel, type ToolResponse, type ToolRunOptions, UTILITY_MODELS, type UpscaleOptions, VIDEO_IMAGE_TO_VIDEO_TOP_15, VIDEO_MODELS, VIDEO_TEXT_TO_VIDEO_TOP_15, type VideoOptions, type VideoResponse, aspectToFalImageSize, aspectToGptSize, buildFalToolRequest, buildGenerateBody, enrichPrompt, estimateCost, estimateVideoCost, getFalKeyFromEnv, isFalToolId, motifEnvSchema, parseMotifEnv, sanitizePrompt };

package/dist/index.js

@@ -3177,7 +3177,6 @@ var FalClient = class {
     });
   }
 };
-var MotifServer = FalClient;
 var MotifError = class extends Error {
   status;
   code;
@@ -3217,7 +3216,6 @@ export {
   IMAGE_TEXT_TO_IMAGE_TOP_20,
   MODELS,
   MotifError,
-  MotifServer,
   RECRAFT_STYLES,
   RESOLUTIONS,
   UTILITY_MODELS,

package/package.json

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